[cli] Add --stdin to read the input video from a pipe by EnesSoydan · Pull Request #598 · Breakthrough/PySceneDetect

EnesSoydan · 2026-11-06T01:02:25Z

Closes #434
Closes #189

Adds a --stdin flag, so a video can be piped in:

ffmpeg -i input.mp4 -c copy -f matroska - | scenedetect --stdin detect-content list-scenes

This went through the task list in #189:

Backend: it uses VideoStreamAv, since PyAV already takes a file-like object. --stdin with another backend is an error, and so is combining it with -i.
Seeking: it isn't possible, so these commands now fail with a clear error before anything is processed: split-video, save-images, load-scenes, and time -s. save-html leaves out images.
Source path: save-fcp and save-otio are rejected as well, because they write a reference to a source file that doesn't exist here.
$VIDEO_NAME: it is set to stdin, so output files get names like stdin-Scenes.csv.

I left split-video from a stream out of this PR.

Two things I ran into while testing:

On Windows, sys.stdin.buffer.seekable() returns True for a pipe, and PyAV then fails with OSError: [Errno 22] when it tries to seek. _PipeReader is a small wrapper that reports the stream as non-seekable.
An MP4 with its index at the end of the file opens from a pipe but decodes no frames, without raising an error. The CLI now logs a critical message with a remux hint and exits with 1, so a pipeline doesn't treat it as success. __main__.py lets SystemExit through so this isn't logged as an unhandled exception. The existing OpenCV "no frames" path still exits with 0; I didn't change that here.

The new tests in tests/test_cli.py write to the CLI through a real pipe. They include a check that the scenes match the same video opened with -i.

I edited docs/cli.rst by hand instead of committing the output of generate_cli_docs.py, because the generator also changed some unrelated lines.

Tested on Windows with Python 3.10 and PyAV 17. I haven't run it on Linux or macOS, or with a real ffmpeg pipe, since ffmpeg isn't installed on my machine. The tests pipe the file's bytes directly.

Breakthrough · 2026-11-08T00:04:38Z

Also FYI I'm trying to get v0.7.3. out right now so I'd like to hold this until after the release just to avoid bringing in any last minute changes. Feel free to continue working on this in the meantime though, I'll make sure we get this landed in the version that we ship just after v0.7.3.

Can you also post a quick comment in each of the linked bugs in the PR description so I can assign those issues to you (so folks know it's taken)? Just something like "I'd like to take this on, staged #598 for this" is sufficient. Thanks.

Breakthrough

Thanks for the PR, this will be cool to see added! See my comment above for requested changes.

v0.7.3 just shipped, so you can rebase this on main now so we can also run the tests after. Thanks.

Closes Breakthrough#434 Closes Breakthrough#189

EnesSoydan · 2026-11-10T02:08:04Z

Rebased on main. The only conflict was in the changelog, so the --stdin entry is now under 0.8. I also commented on #434 and #189 as you asked.

Breakthrough

v0.7.3 just shipped, so you can rebase this on main now so we can also run the tests after. Thanks. PTAL the review comments as well.

Breakthrough

(sorry forgot to post the comments on prev. reply)

Breakthrough · 2026-11-13T01:41:11Z

+            " as an MP4 with its index at the end of the file. Try remuxing to MKV or MPEG-TS:\n"
+            "      ffmpeg -i input.mp4 -c copy -f matroska -\n"
+        )
+        raise SystemExit(1)


Could _detect() return None here like the OpenCV branch above, and have run_scenedetect() report the failure so main() exits with 1? Then the except SystemExit in __main__.py isn't needed.

Breakthrough · 2026-11-13T01:41:11Z

+    "--stdin",
+    is_flag=True,
+    default=False,
+    help="Read the input video from standard input instead of -i/--input. Requires the pyav backend and a container that can be read from a pipe (e.g. MKV or MPEG-TS). Commands that need to seek in the video are not supported.",


Re: the container that can be read part, can we make it more clear how this can be created? e.g. can we reword this to say the MP4 needs its index at the start of the file (ffmpeg -movflags +faststart)? Otherwise, remux to MKV or MPEG-TS? Same text in docs/cli.rst.

Breakthrough · 2026-11-13T01:41:11Z

+def check_not_stdin(ctx: CliContext, command: str) -> None:
+    """Rejects `command` if the input is read from stdin, which cannot seek and has no path."""
+    if ctx.use_stdin:
+        raise click.BadParameter(f"{command} is incompatible with --stdin.", param_hint=command)


This should be click.UsageError(f"{command} is incompatible with --stdin."), the current message repeats the command name in the logged output via the param_hint.

Breakthrough · 2026-11-13T01:41:11Z

    # Make sure a save-images command is in the pipeline for us to use the results from if we need
    # to include images.
-    include_images = not ctx.config.get_value("save-html", "no-images", no_images)
+    no_images = ctx.config.get_value("save-html", "no-images", no_images) or ctx.use_stdin


Could you log a message when --stdin forces no_images?

Breakthrough · 2026-11-13T01:41:11Z

+                "--stdin requires the pyav backend. Install it with `pip install av`.",
+                param_hint="--stdin",
+            )
+        if sys.stdin.isatty():


Should this be sys.stdin is None or sys.stdin.isatty()? sys.stdin is None under pythonw.exe on my Windows computer.

Breakthrough · 2026-11-13T01:41:11Z

+    assert "Processed" not in output
+
+
+def test_cli_stdin_unreadable_container():


Please add a comment that makes it clear this relies on testvideo.mp4 having its moov atom at the end.

- Return None from _detect() when no frames are read from stdin, and exit with 1 from main() when run_scenedetect() reports a failure - Explain in the --stdin help that an MP4 needs its index at the start of the file (-movflags +faststart), otherwise remux to MKV or MPEG-TS - Raise UsageError for commands that are incompatible with --stdin - Warn when save-html leaves out images because of --stdin - Handle sys.stdin being None (e.g. under pythonw.exe) - Add a CONCORDANCE row for --stdin and regenerate docs/cli.rst - Fix pyright errors in _open_video_stream

EnesSoydan · 2026-11-13T16:12:51Z

Thanks for the review! Pushed 97e01e6:

_detect() now returns None for stdin as well, and main() exits with 1 when run_scenedetect() reports a failure, so the except SystemExit is gone. This also makes the OpenCV "no frames" and failed seek paths exit with 1 instead of 0, so I added a changelog line for that. Happy to limit it to stdin if you'd rather keep those as they are.
Reworded the --stdin help (and docs/cli.rst) to mention -movflags +faststart. I checked that a faststart remux of testvideo.mp4 reads fine from a pipe.
UsageError for incompatible commands, a warning when save-html drops images, sys.stdin is None, and the test comment, as suggested.
For CI: added a CONCORDANCE row for --stdin and regenerated docs/cli.rst, and fixed the pyright errors in _open_video_stream.

Breakthrough added the feature label Nov 8, 2026

Breakthrough assigned EnesSoydan Nov 8, 2026

This was referenced Nov 8, 2026

Support of input type "std input" #434

Open

[Feature Request] Support input via pipe #189

Open

Breakthrough requested changes Nov 10, 2026

View reviewed changes

[cli] Add --stdin to read the input video from a pipe

4605bc2

Closes Breakthrough#434 Closes Breakthrough#189

EnesSoydan force-pushed the fix/434-stdin-input branch from 5296354 to 4605bc2 Compare November 10, 2026 02:07

Breakthrough requested changes Nov 13, 2026

View reviewed changes

Merge branch 'main' into fix/434-stdin-input

036fcb0

Breakthrough requested changes Nov 13, 2026

View reviewed changes

Navigation Menu

Repository navigation

[cli] Add --stdin to read the input video from a pipe - #598

[cli] Add --stdin to read the input video from a pipe#598
EnesSoydan wants to merge 3 commits into
Breakthrough:mainfrom
EnesSoydan:fix/434-stdin-input

EnesSoydan commented Nov 6, 2026

Uh oh!

Breakthrough commented Nov 8, 2026 •

edited

Loading

Uh oh!

Breakthrough left a comment •

edited

Loading

Uh oh!

EnesSoydan commented Nov 10, 2026

Uh oh!

Breakthrough left a comment

Uh oh!

Breakthrough left a comment

Uh oh!

Breakthrough Nov 13, 2026

Uh oh!

Breakthrough Nov 13, 2026 •

edited

Loading

Uh oh!

Breakthrough Nov 13, 2026 •

edited

Loading

Uh oh!

Breakthrough Nov 13, 2026

Uh oh!

Breakthrough Nov 13, 2026

Uh oh!

Breakthrough Nov 13, 2026

Uh oh!

EnesSoydan commented Nov 13, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		assert "Processed" not in output


		def test_cli_stdin_unreadable_container():

Conversation

EnesSoydan commented Nov 6, 2026

Uh oh!

Breakthrough commented Nov 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Breakthrough left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

EnesSoydan commented Nov 10, 2026

Uh oh!

Breakthrough left a comment

Choose a reason for hiding this comment

Uh oh!

Breakthrough left a comment

Choose a reason for hiding this comment

Uh oh!

Breakthrough Nov 13, 2026

Choose a reason for hiding this comment

Uh oh!

Breakthrough Nov 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Breakthrough Nov 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Breakthrough Nov 13, 2026

Choose a reason for hiding this comment

Uh oh!

Breakthrough Nov 13, 2026

Choose a reason for hiding this comment

Uh oh!

Breakthrough Nov 13, 2026

Choose a reason for hiding this comment

Uh oh!

EnesSoydan commented Nov 13, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Breakthrough commented Nov 8, 2026 •

edited

Loading

Breakthrough left a comment •

edited

Loading

Breakthrough Nov 13, 2026 •

edited

Loading

Breakthrough Nov 13, 2026 •

edited

Loading