Video capture backend fallback: diagnose AVI open errors

An AVI file that produces an image-sequence filename error does not necessarily need a different name. The application may have reached an image-sequence backend after a video-file backend could not open the input. This distinction matters when you are evaluating recorded footage alongside live camera acquisition. The workflow below separates those paths, checks file access and decoder support, and identifies the backend actually opening the input before you change hardware or rebuild software.

Interpret the backend error before changing the filename

A message containing CAP_IMAGES identifies the image-sequence backend. That backend expects individual image files, often arranged in a numbered sequence. Its filename-parsing error explains why that particular backend rejected the input; it does not establish why a video decoder failed.

With automatic backend selection, the application can try multiple implementations. A filename-parsing message may therefore be a later symptom rather than the original failure. Alternatively, the application may have selected the image-sequence backend explicitly. Check both possibilities before drawing conclusions.

Separate recorded files from live camera acquisition

First establish what the application actually passes to its capture API. A string such as inspection.avi normally represents a file. An integer device index normally requests a live camera through a supported device backend. A pipeline string or network address represents another input path again.

A recording originally made by a USB camera is still a file-decoding task when reopened. The camera does not need to be connected for that test. Conversely, successfully decoding its recording does not prove that live camera access works.

Also distinguish generic USB video devices from industrial cameras requiring a manufacturer-supported SDK or transport layer. A USB connector alone does not establish compatibility with a generic device-index capture API.

For a live device that opens but rejects particular operating modes, use the separate USB camera format-negotiation diagnosis. Keep that investigation separate from AVI file opening.

Verify the file from the application's environment

Check accessibility before changing codecs or rebuilding the library. Relative paths resolve against the process working directory, which can differ between a terminal, an editor and a deployed service.

1. Print the resolved absolute path from inside the failing application.
2. Check that the path identifies a regular, nonempty file.
3. Read a small portion using ordinary file access under the same account.
4. If a mount or network share is involved, repeat with an authorized local copy.

This small Python check isolates filesystem access from video decoding:

from pathlib import Path

path = Path("inspection.avi").resolve(strict=True)
if not path.is_file():
    raise RuntimeError("Input is not a regular file")
if path.stat().st_size == 0:
    raise RuntimeError("Input file is empty")

with path.open("rb") as source:
    prefix = source.read(16)

print("Resolved input:", path)
print("Bytes read:", len(prefix))

Reading bytes proves access, not format validity. A truncated file can pass this check, and a misleading extension can still identify unrelated content. Preserve the original recording while investigating either possibility.

Check the container, encoded stream and first frame

AVI is a container, not a single video encoding. Two AVI files can require different decoders. Support for the container does not automatically mean support for every encoded stream it can contain.

Use a trusted media-inspection utility, obtained through its official distribution, to identify the video encoding, dimensions, nominal frame rate and duration. Check for truncation or missing stream information. Compare these details with a small clip already known to work in the target application.

A desktop player opening the file is useful evidence, but not decisive. That player may use a different decoder stack from the application.

Distinguish these checkpoints:

• File access: the process can read the input bytes.
• Capture opening: a backend accepts the input and initializes.
• Frame decoding: a read returns an actual, nonempty image.
• Sustained processing: repeated reads continue at the required rate.

Do not treat isOpened() alone as proof of successful decoding. The first frame read is a separate test, and later corruption can still interrupt an otherwise successful start.

Inspect the library loaded by the failing process

Build settings only help if they describe the library your application actually loads. Multiple installations can leave an interpreter using a different binary from the one you recently compiled.

Run these checks inside the failing Python environment:

import cv2

print("Loaded module:", cv2.__file__)
print("Library version:", cv2.__version__)
print(cv2.getBuildInformation())

Inspect the video-I/O portion of the build information. Identify which file-decoding backends were enabled, then check diagnostic logs for missing runtime dependencies or initialization failures. A backend constant existing in the API does not prove that its implementation is available and working.

Where supported by your installed version, backend-registry APIs can provide additional information. Their availability varies, so use the documentation matching the loaded version rather than assuming a newer example applies unchanged.

On a different processor architecture, verify the application, library and decoder dependencies together. The binary-compatibility checks for ARM64 acquisition explain that boundary. An evaluation environment's performance configuration does not, by itself, demonstrate that a particular decoder was included.

Compare automatic and explicit backend selection

Use a minimal program without the inspection algorithm, display loop or live-camera SDK. Test the same absolute path with automatic selection and a file-decoder backend expected in your build.

The following example tests CAP_FFMPEG explicitly. Select it only where the build information indicates the corresponding support; another documented file backend may be appropriate in your environment.

import cv2
from pathlib import Path

path = str(Path("inspection.avi").resolve(strict=True))
tests = [
    ("automatic", cv2.CAP_ANY),
    ("explicit file decoder", cv2.CAP_FFMPEG),
]

for label, api in tests:
    capture = cv2.VideoCapture()
    try:
        opened = capture.open(path, api)
        print(label, "opened:", opened)
        if not opened:
            continue

        if hasattr(capture, "getBackendName"):
            print("Selected backend:", capture.getBackendName())

        ok, frame = capture.read()
        valid = ok and frame is not None and frame.size > 0
        print("First frame valid:", valid)
        if valid:
            print("Frame shape:", frame.shape)
    except cv2.error as error:
        print(label, "capture error:", error)
    finally:
        capture.release()

Interpret the results narrowly:

• Explicit decoding works, automatic selection fails: investigate selection policy, configuration and backend diagnostics. An explicit choice can make deployment more predictable.
• Both fail on this file, but a known-good clip works: investigate the original stream's encoding, integrity and supported features.
• Both fail on every known-good clip: prioritize the loaded build, runtime dependencies and file access.
• Both open, but neither returns a frame: investigate decoding rather than filename-pattern rules.

Enable the library's documented video-I/O logging before process startup when necessary. Preserve messages preceding the final exception; those may contain the useful decoder failure.

Separate an opening fix from a performance result

Consider a controlled test clip containing 300 frames at a constant 30 fps. Its nominal duration is 10 seconds. Suppose an explicit backend opens it and decodes every frame, but the decoding loop takes 15 seconds.

The opening problem is resolved in this example, but decoding alone remains slower than the recorded rate. That is a different finding from an image-sequence filename error.

For the throughput test, count successfully decoded frames and time the read loop separately from display and inspection processing. Record the output image format as well. Color conversion and memory copies can affect elapsed time without causing the original open failure.

Do not generalize this arithmetic to variable-frame-rate recordings or trust unverified metadata as ground truth. Use a controlled clip with a known frame count when comparing deployments.

Choose acquisition hardware only after isolating the fault

Replacing a camera will not repair a missing file decoder. If the actual requirement is live acquisition, first define the camera interface and supported software path. Then compare area scan cameras using the camera finder.

The LS-CMR-0166 is a USB3 area scan camera. It is relevant to a separate live-acquisition evaluation, not evidence that an AVI encoding is supported.

The LS-CMR-0053 uses GigE. Evaluate its documented acquisition path independently from the recorded-file decoder.

If you are selecting a dedicated processing platform, review vision controllers against the required camera connections and software environment. Confirm decoder availability independently; camera ports do not establish video-file compatibility.

The broader software-integration tradeoffs help separate acquisition, decoding and application responsibilities before choosing an architecture.

Verify the fix and preserve a reproducible test

Before closing the issue, retain a short acceptance checklist:

• [ ] The application logs whether its source is a file, device index or pipeline.
• [ ] The resolved file path is readable under the deployment account.
• [ ] The loaded library location and build information are recorded.
• [ ] A known-good clip and the original recording have both been tested.
• [ ] The selected backend is recorded after a successful open.
• [ ] Frame decoding succeeds beyond the first read.
• [ ] Playback reaches the expected end, with frame counts interpreted appropriately.
• [ ] Throughput is measured separately from successful opening.
• [ ] The test still passes after restarting the application.

Keep the smallest failing clip, minimal program and relevant diagnostics together, subject to your data-handling requirements. Re-run them after changing the library, decoder dependencies or deployment environment.

For a new live-camera system, start with the camera configuration step. If interface selection remains uncertain, use application support with the input type, required image rate and diagnostic results. Resolve the file-opening failure before using it as a reason to replace acquisition hardware.