edgecut 0.1.0__tar.gz

edgecut-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZeroMarker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

edgecut-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: edgecut
+Version: 0.1.0
+Summary: Frame-accurate H.264/HEVC clips that copy the video between keyframes and re-encode only the edges, using the FFmpeg CLI.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ZeroMarker/edgecut
+Project-URL: Repository, https://github.com/ZeroMarker/edgecut
+Project-URL: Issues, https://github.com/ZeroMarker/edgecut/issues
+Keywords: ffmpeg,video,cut,trim,h264,hevc,lossless
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video :: Conversion
+Classifier: Environment :: Console
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# edgecut
+
+Frame-accurate clips from H.264 and HEVC videos in seconds. edgecut copies the original video between keyframes and re-encodes only the few frames at each edge of the cut, so almost every frame of the clip is bit-identical to the source.
+
+It is a single Python file with no dependencies beyond the standard library. All video work is done by the `ffmpeg` and `ffprobe` command-line tools.
+
+```sh
+edgecut movie.mkv 1:02:03.5 1:04:10 clip.mp4
+```
+
+## Install
+
+Requirements: Python 3.9+, and FFmpeg with libx264 (and libx265 for HEVC sources).
+
+```sh
+uv tool install git+https://github.com/ZeroMarker/edgecut
+# or
+pipx install git+https://github.com/ZeroMarker/edgecut
+```
+
+Or copy `edgecut.py` into your project.
+
+## Usage
+
+```
+edgecut [-v] SOURCE START END OUTPUT
+```
+
+- `START` and `END` are seconds, `MM:SS` or `HH:MM:SS` (fractions allowed). The clip holds every frame shown in [START, END) on the source timeline.
+- `OUTPUT` is an MP4 file with the video tagged `avc1`/`hvc1`, `+faststart`, and timestamps starting at 0.
+- `-v` prints the plan and every FFmpeg command.
+- Exit status: `0` success, `2` source or range not supported (nothing was written; use a full re-encode), `1` a step or the output check failed.
+
+From Python:
+
+```python
+import tempfile, edgecut
+
+with tempfile.TemporaryDirectory() as work:
+    try:
+        clip = edgecut.cut('movie.mp4', 3723.5, 3850.0, work)  # returns work/clip.mp4
+    except edgecut.Unsupported:   # raised before anything runs
+        ...                       # fall back to a full re-encode
+    except edgecut.CutFailed:     # a step or the output check failed
+        ...
+```
+
+`cut()` takes optional `run(argv, engine) -> (returncode, output)` and `event(status, **details)` callbacks, so an application can run the FFmpeg commands under its own logging and timeouts.
+
+## How it works
+
+```
+source   ──K0──────s──K1════════════════════K2──e────K3──
+clip               [head)[      body       )[tail)
+                   re-     stream-copied     re-
+                   encoded                   encoded
+```
+
+1. **Plan** with ffprobe, without decoding. List the video packets from the keyframe before `start` to 3 s past `end` (with B-frames, frames shown just before `end` can come later in decode order). K1 is the first IDR keyframe at or after `start`, K2 the last at or before `end`; the NAL unit type of each candidate is checked (H.264 5, HEVC 19/20). The clip is rejected if it has fewer than two IDR keyframes or any packet between them is shown outside [K1, K2) (open GOP).
+2. **Body.** Stream-copy [K1, K2) to MPEG-TS with the source timestamps and in-band parameter sets.
+3. **Head and tail.** Re-encode [start, K1) and [K2, end) with libx264 (`veryfast`, CRF 16) or libx265 (`superfast`, CRF 18), without B-frames, matching the source pixel format, H.264 profile, colour properties and time base. Their DTS is shifted by the body's reorder delay, read from the written body because Matroska stores no DTS, so DTS keeps increasing across both joins.
+4. **Mux.** Concatenate the TS parts, add the source audio (AAC/MP3 copied, others encoded to AAC), shift the first frame to 0, and write MP4.
+5. **Check.** The frame count must equal the plan, the duration must be within 0.5 s of the clip, and FFmpeg must decode 2 s around the start and each join without errors.
+
+Seeking only positions the demuxer at some earlier keyframe: Matroska seeks to a cue, and with `-copyts` FFmpeg's own `-ss` trimming is offset by the container start time. So every step selects frames and packets by source PTS: the `noise` bitstream filter's `drop` expression for copied packets, and `select`/`atrim` for decoded frames.
+
+Only the clip's own packets are read, so the time does not grow with the length of the source. It is dominated by encoding the edges, so it follows the source's keyframe interval.
+
+## Results
+
+On real 1080p–1440p sources (MP4 and MKV, clips of 28–140 s), compared with a frame-accurate decode of the same range:
+
+- 3.4–16.5 s per clip (median 5.8 s) versus about 145 s for a full libx264 re-encode of the same clip.
+- Same frame count as the reference; all copied frames bit-identical; re-encoded edge frames at 47–69 dB PSNR.
+- Audio packets identical to the source; video and audio start at 0; timestamps within 0.011 ms of the source.
+- Plays in Chromium without media errors, including seeks across the joins.
+
+## Limitations
+
+- Video codecs: H.264 and HEVC with IDR keyframes. Open-GOP sources, other codecs, rotated video, and clips shorter than about two keyframe intervals raise `Unsupported`.
+- Only the first video stream and the first audio stream are kept; subtitles, chapters and metadata are dropped.
+- Not yet verified: HEVC output in browsers, and Safari/iOS playback across the joins, where parameter sets change in-band under the `avc1`/`hvc1` tags.
+
+## Tests
+
+```sh
+python3 -m unittest discover -s tests -v
+```
+
+The tests generate short videos with FFmpeg and compare every decoded frame of each clip with the source range: H.264 with B-frames, HEVC, 10-bit, Matroska, clips starting at 0, and start/end exactly on keyframes. They also check rejection of unsupported sources and errors from failed steps.
+
+## License
+
+MIT
+
+Release maintainers: see [RELEASING.md](RELEASING.md) for packaging checks and the
+PyPI Trusted Publishing workflow.

edgecut-0.1.0/README.md

@@ -0,0 +1,97 @@
+# edgecut
+
+Frame-accurate clips from H.264 and HEVC videos in seconds. edgecut copies the original video between keyframes and re-encodes only the few frames at each edge of the cut, so almost every frame of the clip is bit-identical to the source.
+
+It is a single Python file with no dependencies beyond the standard library. All video work is done by the `ffmpeg` and `ffprobe` command-line tools.
+
+```sh
+edgecut movie.mkv 1:02:03.5 1:04:10 clip.mp4
+```
+
+## Install
+
+Requirements: Python 3.9+, and FFmpeg with libx264 (and libx265 for HEVC sources).
+
+```sh
+uv tool install git+https://github.com/ZeroMarker/edgecut
+# or
+pipx install git+https://github.com/ZeroMarker/edgecut
+```
+
+Or copy `edgecut.py` into your project.
+
+## Usage
+
+```
+edgecut [-v] SOURCE START END OUTPUT
+```
+
+- `START` and `END` are seconds, `MM:SS` or `HH:MM:SS` (fractions allowed). The clip holds every frame shown in [START, END) on the source timeline.
+- `OUTPUT` is an MP4 file with the video tagged `avc1`/`hvc1`, `+faststart`, and timestamps starting at 0.
+- `-v` prints the plan and every FFmpeg command.
+- Exit status: `0` success, `2` source or range not supported (nothing was written; use a full re-encode), `1` a step or the output check failed.
+
+From Python:
+
+```python
+import tempfile, edgecut
+
+with tempfile.TemporaryDirectory() as work:
+    try:
+        clip = edgecut.cut('movie.mp4', 3723.5, 3850.0, work)  # returns work/clip.mp4
+    except edgecut.Unsupported:   # raised before anything runs
+        ...                       # fall back to a full re-encode
+    except edgecut.CutFailed:     # a step or the output check failed
+        ...
+```
+
+`cut()` takes optional `run(argv, engine) -> (returncode, output)` and `event(status, **details)` callbacks, so an application can run the FFmpeg commands under its own logging and timeouts.
+
+## How it works
+
+```
+source   ──K0──────s──K1════════════════════K2──e────K3──
+clip               [head)[      body       )[tail)
+                   re-     stream-copied     re-
+                   encoded                   encoded
+```
+
+1. **Plan** with ffprobe, without decoding. List the video packets from the keyframe before `start` to 3 s past `end` (with B-frames, frames shown just before `end` can come later in decode order). K1 is the first IDR keyframe at or after `start`, K2 the last at or before `end`; the NAL unit type of each candidate is checked (H.264 5, HEVC 19/20). The clip is rejected if it has fewer than two IDR keyframes or any packet between them is shown outside [K1, K2) (open GOP).
+2. **Body.** Stream-copy [K1, K2) to MPEG-TS with the source timestamps and in-band parameter sets.
+3. **Head and tail.** Re-encode [start, K1) and [K2, end) with libx264 (`veryfast`, CRF 16) or libx265 (`superfast`, CRF 18), without B-frames, matching the source pixel format, H.264 profile, colour properties and time base. Their DTS is shifted by the body's reorder delay, read from the written body because Matroska stores no DTS, so DTS keeps increasing across both joins.
+4. **Mux.** Concatenate the TS parts, add the source audio (AAC/MP3 copied, others encoded to AAC), shift the first frame to 0, and write MP4.
+5. **Check.** The frame count must equal the plan, the duration must be within 0.5 s of the clip, and FFmpeg must decode 2 s around the start and each join without errors.
+
+Seeking only positions the demuxer at some earlier keyframe: Matroska seeks to a cue, and with `-copyts` FFmpeg's own `-ss` trimming is offset by the container start time. So every step selects frames and packets by source PTS: the `noise` bitstream filter's `drop` expression for copied packets, and `select`/`atrim` for decoded frames.
+
+Only the clip's own packets are read, so the time does not grow with the length of the source. It is dominated by encoding the edges, so it follows the source's keyframe interval.
+
+## Results
+
+On real 1080p–1440p sources (MP4 and MKV, clips of 28–140 s), compared with a frame-accurate decode of the same range:
+
+- 3.4–16.5 s per clip (median 5.8 s) versus about 145 s for a full libx264 re-encode of the same clip.
+- Same frame count as the reference; all copied frames bit-identical; re-encoded edge frames at 47–69 dB PSNR.
+- Audio packets identical to the source; video and audio start at 0; timestamps within 0.011 ms of the source.
+- Plays in Chromium without media errors, including seeks across the joins.
+
+## Limitations
+
+- Video codecs: H.264 and HEVC with IDR keyframes. Open-GOP sources, other codecs, rotated video, and clips shorter than about two keyframe intervals raise `Unsupported`.
+- Only the first video stream and the first audio stream are kept; subtitles, chapters and metadata are dropped.
+- Not yet verified: HEVC output in browsers, and Safari/iOS playback across the joins, where parameter sets change in-band under the `avc1`/`hvc1` tags.
+
+## Tests
+
+```sh
+python3 -m unittest discover -s tests -v
+```
+
+The tests generate short videos with FFmpeg and compare every decoded frame of each clip with the source range: H.264 with B-frames, HEVC, 10-bit, Matroska, clips starting at 0, and start/end exactly on keyframes. They also check rejection of unsupported sources and errors from failed steps.
+
+## License
+
+MIT
+
+Release maintainers: see [RELEASING.md](RELEASING.md) for packaging checks and the
+PyPI Trusted Publishing workflow.

edgecut-0.1.0/edgecut.egg-info/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: edgecut
+Version: 0.1.0
+Summary: Frame-accurate H.264/HEVC clips that copy the video between keyframes and re-encode only the edges, using the FFmpeg CLI.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ZeroMarker/edgecut
+Project-URL: Repository, https://github.com/ZeroMarker/edgecut
+Project-URL: Issues, https://github.com/ZeroMarker/edgecut/issues
+Keywords: ffmpeg,video,cut,trim,h264,hevc,lossless
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video :: Conversion
+Classifier: Environment :: Console
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# edgecut
+
+Frame-accurate clips from H.264 and HEVC videos in seconds. edgecut copies the original video between keyframes and re-encodes only the few frames at each edge of the cut, so almost every frame of the clip is bit-identical to the source.
+
+It is a single Python file with no dependencies beyond the standard library. All video work is done by the `ffmpeg` and `ffprobe` command-line tools.
+
+```sh
+edgecut movie.mkv 1:02:03.5 1:04:10 clip.mp4
+```
+
+## Install
+
+Requirements: Python 3.9+, and FFmpeg with libx264 (and libx265 for HEVC sources).
+
+```sh
+uv tool install git+https://github.com/ZeroMarker/edgecut
+# or
+pipx install git+https://github.com/ZeroMarker/edgecut
+```
+
+Or copy `edgecut.py` into your project.
+
+## Usage
+
+```
+edgecut [-v] SOURCE START END OUTPUT
+```
+
+- `START` and `END` are seconds, `MM:SS` or `HH:MM:SS` (fractions allowed). The clip holds every frame shown in [START, END) on the source timeline.
+- `OUTPUT` is an MP4 file with the video tagged `avc1`/`hvc1`, `+faststart`, and timestamps starting at 0.
+- `-v` prints the plan and every FFmpeg command.
+- Exit status: `0` success, `2` source or range not supported (nothing was written; use a full re-encode), `1` a step or the output check failed.
+
+From Python:
+
+```python
+import tempfile, edgecut
+
+with tempfile.TemporaryDirectory() as work:
+    try:
+        clip = edgecut.cut('movie.mp4', 3723.5, 3850.0, work)  # returns work/clip.mp4
+    except edgecut.Unsupported:   # raised before anything runs
+        ...                       # fall back to a full re-encode
+    except edgecut.CutFailed:     # a step or the output check failed
+        ...
+```
+
+`cut()` takes optional `run(argv, engine) -> (returncode, output)` and `event(status, **details)` callbacks, so an application can run the FFmpeg commands under its own logging and timeouts.
+
+## How it works
+
+```
+source   ──K0──────s──K1════════════════════K2──e────K3──
+clip               [head)[      body       )[tail)
+                   re-     stream-copied     re-
+                   encoded                   encoded
+```
+
+1. **Plan** with ffprobe, without decoding. List the video packets from the keyframe before `start` to 3 s past `end` (with B-frames, frames shown just before `end` can come later in decode order). K1 is the first IDR keyframe at or after `start`, K2 the last at or before `end`; the NAL unit type of each candidate is checked (H.264 5, HEVC 19/20). The clip is rejected if it has fewer than two IDR keyframes or any packet between them is shown outside [K1, K2) (open GOP).
+2. **Body.** Stream-copy [K1, K2) to MPEG-TS with the source timestamps and in-band parameter sets.
+3. **Head and tail.** Re-encode [start, K1) and [K2, end) with libx264 (`veryfast`, CRF 16) or libx265 (`superfast`, CRF 18), without B-frames, matching the source pixel format, H.264 profile, colour properties and time base. Their DTS is shifted by the body's reorder delay, read from the written body because Matroska stores no DTS, so DTS keeps increasing across both joins.
+4. **Mux.** Concatenate the TS parts, add the source audio (AAC/MP3 copied, others encoded to AAC), shift the first frame to 0, and write MP4.
+5. **Check.** The frame count must equal the plan, the duration must be within 0.5 s of the clip, and FFmpeg must decode 2 s around the start and each join without errors.
+
+Seeking only positions the demuxer at some earlier keyframe: Matroska seeks to a cue, and with `-copyts` FFmpeg's own `-ss` trimming is offset by the container start time. So every step selects frames and packets by source PTS: the `noise` bitstream filter's `drop` expression for copied packets, and `select`/`atrim` for decoded frames.
+
+Only the clip's own packets are read, so the time does not grow with the length of the source. It is dominated by encoding the edges, so it follows the source's keyframe interval.
+
+## Results
+
+On real 1080p–1440p sources (MP4 and MKV, clips of 28–140 s), compared with a frame-accurate decode of the same range:
+
+- 3.4–16.5 s per clip (median 5.8 s) versus about 145 s for a full libx264 re-encode of the same clip.
+- Same frame count as the reference; all copied frames bit-identical; re-encoded edge frames at 47–69 dB PSNR.
+- Audio packets identical to the source; video and audio start at 0; timestamps within 0.011 ms of the source.
+- Plays in Chromium without media errors, including seeks across the joins.
+
+## Limitations
+
+- Video codecs: H.264 and HEVC with IDR keyframes. Open-GOP sources, other codecs, rotated video, and clips shorter than about two keyframe intervals raise `Unsupported`.
+- Only the first video stream and the first audio stream are kept; subtitles, chapters and metadata are dropped.
+- Not yet verified: HEVC output in browsers, and Safari/iOS playback across the joins, where parameter sets change in-band under the `avc1`/`hvc1` tags.
+
+## Tests
+
+```sh
+python3 -m unittest discover -s tests -v
+```
+
+The tests generate short videos with FFmpeg and compare every decoded frame of each clip with the source range: H.264 with B-frames, HEVC, 10-bit, Matroska, clips starting at 0, and start/end exactly on keyframes. They also check rejection of unsupported sources and errors from failed steps.
+
+## License
+
+MIT
+
+Release maintainers: see [RELEASING.md](RELEASING.md) for packaging checks and the
+PyPI Trusted Publishing workflow.

edgecut-0.1.0/edgecut.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+edgecut.py
+pyproject.toml
+edgecut.egg-info/PKG-INFO
+edgecut.egg-info/SOURCES.txt
+edgecut.egg-info/dependency_links.txt
+edgecut.egg-info/entry_points.txt
+edgecut.egg-info/top_level.txt
+tests/test_edgecut.py

edgecut-0.1.0/edgecut.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

edgecut-0.1.0/edgecut.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+edgecut = edgecut:main

edgecut-0.1.0/edgecut.egg-info/top_level.txt

@@ -0,0 +1 @@
+edgecut

edgecut-0.1.0/edgecut.py

@@ -0,0 +1,336 @@
+"""edgecut: frame-accurate MP4 clips that re-encode only the edges of the cut.
+
+A clip [start, end) of an H.264 or HEVC source is built from three parts on the
+source timeline:
+
+    head  [start, K1)  re-encoded; K1 is the first IDR keyframe at or after start
+    body  [K1, K2)     stream-copied, packet for packet
+    tail  [K2, end)    re-encoded; K2 is the last IDR keyframe at or before end
+
+IDR keyframes close their GOP, so the copied body never references a frame
+outside it. Each part is written to MPEG-TS with the source timestamps and
+in-band parameter sets, the parts are joined byte-wise, and the result is muxed
+to MP4 with the source audio. Only the clip's own packets are probed, so the
+cost does not grow with the length of the source file. Uses the FFmpeg CLI only.
+"""
+import argparse
+from fractions import Fraction
+import json
+from pathlib import Path
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import tempfile
+
+__version__ = '0.1.0'
+ENGINE = 'edgecut'
+
+# codec: (encoder, extra encoder args, MP4 tag). The parts carry in-band
+# parameter sets; the widely supported avc1/hvc1 tags are used anyway, as for
+# FFmpeg's own MPEG-TS to MP4 remuxes (Safari rejects hev1).
+CODECS = {
+    'h264': ('libx264', ['-preset', 'veryfast', '-crf', '16', '-bf', '0'], 'avc1'),
+    'hevc': ('libx265', ['-preset', 'superfast', '-crf', '18', '-x265-params', 'bframes=0:log-level=error'], 'hvc1'),
+}
+IDR_TYPES = {'h264': {5}, 'hevc': {19, 20}}
+H264_PROFILES = {'Baseline': 'baseline', 'Constrained Baseline': 'baseline', 'Main': 'main', 'High': 'high',
+                 'High 10': 'high10', 'High 4:2:2': 'high422', 'High 4:4:4 Predictive': 'high444'}
+COPY_AUDIO = {'aac', 'mp3'}
+# Added to every intermediate timestamp so parts starting near zero never go
+# negative in MPEG-TS (which cannot store negative timestamps).
+TS_OFFSET = 10
+EPSILON = Fraction(1, 1000)
+
+
+class Unsupported(Exception):
+    """The source or range does not suit an edgecut; nothing was run."""
+
+
+class CutFailed(Exception):
+    """An edgecut step failed or produced an implausible result."""
+
+
+def seconds(value):
+    return f'{float(value):.6f}'
+
+
+def ffprobe(args, timeout=120, error=Unsupported):
+    try:
+        result = subprocess.run(['ffprobe', '-v', 'error', *args, '-of', 'json'], stdin=subprocess.DEVNULL,
+                                capture_output=True, timeout=timeout)
+    except subprocess.TimeoutExpired:
+        raise error(f'ffprobe took over {timeout} seconds') from None
+    if result.returncode:
+        raise error('ffprobe failed: ' + result.stderr.decode('utf-8', 'replace').strip()[-300:])
+    try:
+        return json.loads(result.stdout or b'{}')
+    except ValueError:
+        raise error('ffprobe returned invalid JSON') from None
+
+
+def first_nal_type(source, codec, at, timeout=120):
+    """Type of the first picture NAL unit of the keyframe at `at` seconds."""
+    bsf = 'h264_mp4toannexb' if codec == 'h264' else 'hevc_mp4toannexb'
+    try:
+        data = subprocess.run(['ffmpeg', '-v', 'error', '-nostdin', '-ss', seconds(at + EPSILON), '-i', str(source),
+                               '-map', '0:v:0', '-c', 'copy', '-copypriorss', '1', '-bsf:v', bsf, '-frames:v', '1',
+                               '-f', codec, '-'], stdin=subprocess.DEVNULL, capture_output=True, timeout=timeout).stdout
+    except subprocess.TimeoutExpired:
+        raise Unsupported(f'reading the keyframe at {float(at)} took over {timeout} seconds') from None
+    position = 0
+    while (position := data.find(b'\x00\x00\x01', position) + 3) >= 3 and position < len(data):
+        header = data[position]
+        nal = header & 0x1f if codec == 'h264' else header >> 1 & 0x3f
+        if (nal in (1, 5)) if codec == 'h264' else nal < 32:
+            return nal
+    return None
+
+
+def plan(source, start, end):
+    """Probe the source and decide the three parts, or raise Unsupported."""
+    info = ffprobe(['-show_entries', 'stream=index,codec_type,codec_name,profile,pix_fmt,time_base,color_range,'
+                    'color_space,color_transfer,color_primaries:stream_disposition=attached_pic:'
+                    'stream_side_data=rotation:format=duration', str(source)])
+    streams = info.get('streams', [])
+    video = next((s for s in streams if s.get('codec_type') == 'video'
+                  and not s.get('disposition', {}).get('attached_pic')), None)
+    audio = next((s for s in streams if s.get('codec_type') == 'audio'), None)
+    if video is None:
+        raise Unsupported('no video stream')
+    codec = video.get('codec_name')
+    if codec not in CODECS:
+        raise Unsupported(f'unsupported video codec {codec}')
+    if any(side.get('rotation') for side in video.get('side_data_list', [])):
+        raise Unsupported('rotated video')
+    duration = float(info.get('format', {}).get('duration', 'nan'))
+    if not 0 <= start < end <= duration:
+        raise Unsupported(f'range is outside the source duration {duration}')
+    base = Fraction(video['time_base'])
+    # Read past the end: with B-frames, frames shown before `end` can follow a
+    # later-shown frame in decode order.
+    listed = ffprobe(['-select_streams', str(video['index']), '-read_intervals', f'{seconds(start)}%{seconds(end + 3)}',
+                      '-show_entries', 'packet=pts,flags', str(source)], timeout=600)['packets']
+    # Packets in decode order. Only PTS is used: Matroska stores no DTS.
+    if any(p.get('pts') is None for p in listed):
+        raise Unsupported('packets without timestamps')
+    packets = [(Fraction(p['pts']) * base, 'K' in p.get('flags', '')) for p in listed]
+    s, e = Fraction(start), Fraction(end)
+    frames = sorted(pts for pts, _ in packets if s <= pts < e)
+    if not frames:
+        raise Unsupported('no frames in range')
+    keys = [i for i, (pts, key) in enumerate(packets) if key and s <= pts <= e]
+    idr = {}
+
+    def is_idr(i):
+        if i not in idr:
+            idr[i] = first_nal_type(source, codec, packets[i][0]) in IDR_TYPES[codec]
+        return idr[i]
+
+    first = next((i for i in keys if is_idr(i)), None)
+    last = next((i for i in reversed(keys) if first is not None and i > first and is_idr(i)), None)
+    if first is None or last is None or packets[first][0] >= e:
+        raise Unsupported('fewer than two IDR keyframes in the clip')
+    k1, k2 = packets[first][0], packets[last][0]
+    body = packets[first:last]
+    # The body is selected by PTS, so it must be exactly the packets between the keyframes.
+    if any(not k1 <= pts < k2 for pts, _ in body) or sum(k1 <= pts < k2 for pts, _ in packets) != len(body):
+        raise Unsupported('open GOP around the keyframes')
+    return {
+        'codec': codec, 'video': video, 'audio': audio,
+        'first_frame': frames[0], 'k1': k1, 'k2': k2,
+        'head_frames': sum(1 for pts in frames if pts < k1),
+        'body_frames': len(body),
+        'tail_frames': sum(1 for pts in frames if pts >= k2),
+        'start': s, 'end': e,
+    }
+
+
+def encoder_args(p):
+    video, codec = p['video'], p['codec']
+    encoder, extra, _ = CODECS[codec]
+    args = ['-c:v', encoder, *extra, '-pix_fmt', video['pix_fmt']]
+    if codec == 'h264' and video.get('profile') in H264_PROFILES:
+        args += ['-profile:v', H264_PROFILES[video['profile']]]
+    for option, key in (('-color_range', 'color_range'), ('-colorspace', 'color_space'),
+                        ('-color_trc', 'color_transfer'), ('-color_primaries', 'color_primaries')):
+        if video.get(key) not in (None, 'unknown', 'reserved'):
+            args += [option, video[key]]
+    return args
+
+
+def ts_output(path, delay=0):
+    args = ['-fps_mode', 'passthrough', '-enc_time_base:v', '-1'] if delay is not None else []
+    if delay:
+        args += ['-bsf:v', f'setts=dts=DTS-{float(delay)!r}/TB']
+    return [*args, '-output_ts_offset', str(TS_OFFSET), '-mpegts_copyts', '1', '-muxdelay', '0',
+            '-muxpreload', '0', '-f', 'mpegts', str(path)]
+
+
+def between(low, high):
+    """noise bitstream filter expression dropping packets outside [low, high)."""
+    return f'noise=drop=lt(pts*tb\\,{float(low - EPSILON)!r})+gte(pts*tb\\,{float(high - EPSILON)!r})'
+
+
+# Seeking only positions the demuxer at some earlier keyframe (Matroska seeks to
+# a cue, and with -copyts FFmpeg's own -ss trimming is offset by the container
+# start time), so every step selects its frames or packets by source PTS.
+
+def body_command(source, p, work):
+    return ['ffmpeg', '-nostdin', '-y', '-copyts', '-ss', seconds(p['k1']), '-to', seconds(p['k2'] + 1),
+            '-i', str(source), '-map', f"0:{p['video']['index']}", '-c', 'copy', '-copypriorss', '1',
+            '-bsf:v', between(p['k1'], p['k2']), *ts_output(work / 'body.ts', None)]
+
+
+def edge_command(source, p, work, name, first, frames, delay):
+    """Re-encode `frames` frames starting at the frame shown at `first`."""
+    return ['ffmpeg', '-nostdin', '-y', '-copyts', '-noaccurate_seek', '-ss', seconds(first - EPSILON),
+            '-i', str(source), '-map', f"0:{p['video']['index']}",
+            '-vf', f'select=gte(t\\,{float(first - EPSILON)!r})', '-frames:v', str(frames), *encoder_args(p),
+            *ts_output(work / f'{name}.ts', delay)]
+
+
+def body_timing(work):
+    """(first PTS - first DTS, last DTS) of the copied body, in source seconds."""
+    packets = ffprobe(['-show_entries', 'packet=pts_time,dts_time', str(work / 'body.ts')], error=CutFailed)['packets']
+    if not packets:
+        raise CutFailed('the copied body is empty')
+    first, last = packets[0], packets[-1]
+    return (Fraction(first['pts_time']) - Fraction(first['dts_time']),
+            Fraction(last['dts_time']) - TS_OFFSET)
+
+
+def edge_delays(p, timing):
+    """DTS shifts for the re-encoded head and tail.
+
+    They have no B-frames, so their DTS equals PTS. Shifting the head by the
+    body's reorder delay ends it before the body's first DTS; the tail must
+    start after the body's last DTS.
+    """
+    delay, body_last_dts = timing
+    tail = delay if p['k2'] - delay > body_last_dts else (p['k2'] - body_last_dts) / 2
+    return delay, tail
+
+
+def mux_command(source, p, work, parts):
+    command = ['ffmpeg', '-nostdin', '-y', '-copyts', '-itsoffset', str(-TS_OFFSET),
+               '-i', 'concat:' + '|'.join(str(work / f'{part}.ts') for part in parts)]
+    maps = ['-map', '0:v']
+    if p['audio']:
+        command += ['-noaccurate_seek', '-ss', seconds(p['start']), '-to', seconds(p['end'] + 1), '-i', str(source)]
+        maps += ['-map', f"1:{p['audio']['index']}"]
+        if p['audio']['codec_name'] in COPY_AUDIO:
+            maps += ['-c:a', 'copy', '-copypriorss:a', '1', '-bsf:a', between(p['start'], p['end'])]
+        else:
+            maps += ['-af', f"atrim=start={float(p['start'])!r}:end={float(p['end'])!r}", '-c:a', 'aac', '-b:a', '192k']
+    return [*command, *maps, '-c:v', 'copy', '-tag:v', CODECS[p['codec']][2], '-output_ts_offset',
+            seconds(-p['first_frame']), '-map_metadata', '-1', '-movflags', '+faststart', str(work / 'clip.mp4')]
+
+
+def verify(p, output, run):
+    """Check frame count and duration, and decode around each join."""
+    info = ffprobe(['-count_packets', '-show_entries', 'stream=codec_type,nb_read_packets:format=duration',
+                    str(output)], error=CutFailed)
+    count = next((int(s['nb_read_packets']) for s in info.get('streams', []) if s.get('codec_type') == 'video'), 0)
+    expected = p['head_frames'] + p['body_frames'] + p['tail_frames']
+    if count != expected:
+        raise CutFailed(f'output has {count} video frames instead of {expected}')
+    duration = float(info.get('format', {}).get('duration', 'nan'))
+    if not abs(duration - float(p['end'] - p['start'])) <= 0.5:
+        raise CutFailed(f"output lasts {duration} seconds instead of {float(p['end'] - p['start'])}")
+    joins = [0] + [float(k - p['first_frame']) for k, n in ((p['k1'], p['head_frames']), (p['k2'], p['tail_frames'])) if n]
+    command = ['ffmpeg', '-nostdin', '-v', 'error']
+    for join in joins:
+        command += ['-ss', seconds(max(0, join - 1)), '-t', '2', '-i', str(output)]
+    for index in range(len(joins)):
+        command += ['-map', f'{index}:v', '-f', 'null', '-']
+    returncode, text = run(command, ENGINE)
+    if returncode or text.strip():
+        raise CutFailed('decode errors near a join: ' + text.strip()[-300:])
+
+
+def run_quietly(command, _engine=ENGINE):
+    """Default runner: run one command and return (returncode, stderr text)."""
+    result = subprocess.run(command, stdin=subprocess.DEVNULL, capture_output=True, text=True, errors='replace')
+    return result.returncode, result.stderr
+
+
+def cut(source, start, end, work, run=run_quietly, event=lambda status, **details: None):
+    """Write the clip [start, end) seconds of `source` to work/clip.mp4 and return its path.
+
+    `run(argv, engine)` runs and logs one command and returns (returncode,
+    output); `event(status, **details)` logs a step. Raises Unsupported before
+    running anything, or CutFailed afterwards.
+    """
+    source, work = Path(source), Path(work)
+    p = plan(source, start, end)
+    event('plan', engine=ENGINE, codec=p['codec'], k1=float(p['k1']), k2=float(p['k2']),
+          head_frames=p['head_frames'], body_frames=p['body_frames'], tail_frames=p['tail_frames'])
+    def step(name, command):
+        returncode, text = run(command, ENGINE)
+        if returncode:
+            raise CutFailed(f'{name} step exited with {returncode}: ' + text.strip()[-300:])
+
+    step('body', body_command(source, p, work))
+    head_delay, tail_delay = edge_delays(p, body_timing(work))
+    parts = ['body']
+    if p['head_frames']:
+        step('head', edge_command(source, p, work, 'head', p['first_frame'], p['head_frames'], head_delay))
+        parts.insert(0, 'head')
+    if p['tail_frames']:
+        step('tail', edge_command(source, p, work, 'tail', p['k2'], p['tail_frames'], tail_delay))
+        parts.append('tail')
+    step('mux', mux_command(source, p, work, parts))
+    output = work / 'clip.mp4'
+    verify(p, output, run)
+    return output
+
+
+def parse_time(value):
+    """Seconds from '83.5', '1:23.5' or '0:01:23.5'."""
+    if not re.fullmatch(r'(\d+:){0,2}\d+(\.\d+)?', value):
+        raise argparse.ArgumentTypeError(f'invalid time {value!r}; use seconds, MM:SS or HH:MM:SS')
+    *rest, last = value.split(':')
+    if any(int(part) >= 60 for part in rest[1:]) or (rest and float(last) >= 60):
+        raise argparse.ArgumentTypeError(f'invalid time {value!r}')
+    total = 0.0
+    for part in rest:
+        total = total * 60 + int(part)
+    return total * 60 + float(last) if rest else float(last)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog='edgecut', description='Cut a frame-accurate MP4 clip from an H.264 or HEVC '
+                                     'video, copying the video between keyframes and re-encoding only the edges.')
+    parser.add_argument('source', type=Path)
+    parser.add_argument('start', type=parse_time, help='seconds, MM:SS or HH:MM:SS (inclusive)')
+    parser.add_argument('end', type=parse_time, help='seconds, MM:SS or HH:MM:SS (exclusive)')
+    parser.add_argument('output', type=Path, help='MP4 file to write')
+    parser.add_argument('-v', '--verbose', action='store_true', help='print the plan and every FFmpeg command')
+    parser.add_argument('--version', action='version', version=f'%(prog)s {__version__}')
+    args = parser.parse_args(argv)
+
+    def run(command, engine=ENGINE):
+        if args.verbose:
+            print('+', shlex.join(command), file=sys.stderr)
+        return run_quietly(command, engine)
+
+    def event(status, **details):
+        if args.verbose:
+            print(status, json.dumps(details), file=sys.stderr)
+
+    try:
+        with tempfile.TemporaryDirectory(prefix='edgecut-') as work:
+            shutil.copyfile(cut(args.source, args.start, args.end, work, run, event), args.output)
+    except Unsupported as exc:
+        print(f'edgecut: not supported: {exc} (use a full re-encode instead)', file=sys.stderr)
+        return 2
+    except (CutFailed, OSError) as exc:
+        print(f'edgecut: failed: {exc}', file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

edgecut-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "edgecut"
+version = "0.1.0"
+description = "Frame-accurate H.264/HEVC clips that copy the video between keyframes and re-encode only the edges, using the FFmpeg CLI."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["ffmpeg", "video", "cut", "trim", "h264", "hevc", "lossless"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Video :: Conversion",
+    "Environment :: Console",
+]
+
+[project.scripts]
+edgecut = "edgecut:main"
+
+[project.urls]
+Homepage = "https://github.com/ZeroMarker/edgecut"
+Repository = "https://github.com/ZeroMarker/edgecut"
+Issues = "https://github.com/ZeroMarker/edgecut/issues"
+
+[tool.setuptools]
+py-modules = ["edgecut"]

edgecut-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

edgecut-0.1.0/tests/test_edgecut.py

@@ -0,0 +1,121 @@
+"""Cut generated videos and compare every decoded frame with the source range."""
+import json
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from unittest.mock import Mock, patch
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+import edgecut  # noqa: E402
+
+H264 = ('-c:v', 'libx264', '-g', '25', '-bf', '2')
+
+
+def make_video(path, *codec_args, seconds=8):
+    """A test video with a keyframe every second, B-frames, and AAC audio."""
+    subprocess.run(['ffmpeg', '-v', 'error', '-f', 'lavfi', '-i', 'testsrc2=s=160x90:r=25', '-f', 'lavfi',
+                    '-i', 'sine=f=440:r=48000', '-t', str(seconds), *(codec_args or H264), '-c:a', 'aac', str(path)],
+                   check=True)
+
+
+def frame_hashes(path, start=None, end=None):
+    """MD5 of each decoded video frame, optionally only frames shown in [start, end)."""
+    select = ['-vf', f'select=gte(t\\,{start})*lt(t\\,{end})'] if start is not None else []
+    output = subprocess.check_output(['ffmpeg', '-v', 'error', '-copyts', '-i', str(path), '-map', '0:v', *select,
+                                      '-fps_mode', 'passthrough', '-f', 'framemd5', '-'], text=True)
+    return [line.rsplit(',', 1)[1].strip() for line in output.splitlines() if not line.startswith('#')]
+
+
+@unittest.skipUnless(shutil.which('ffmpeg') and shutil.which('ffprobe'), 'FFmpeg and FFprobe required')
+class EdgecutTests(unittest.TestCase):
+    def setUp(self):
+        temporary = tempfile.TemporaryDirectory()
+        self.addCleanup(temporary.cleanup)
+        self.directory = Path(temporary.name)
+
+    def cut(self, source, start, end):
+        events = []
+        work = self.directory / f'work-{len(list(self.directory.glob("work-*")))}'
+        work.mkdir()
+        output = edgecut.cut(source, start, end, work, event=lambda status, **d: events.append((status, d)))
+        return output, events
+
+    def assert_exact_clip(self, output, source, start, end, copied):
+        """Same frames as the source range; the copied ones bit-identical."""
+        expected, actual = frame_hashes(source, start, end), frame_hashes(output)
+        self.assertEqual(len(actual), len(expected))
+        self.assertGreaterEqual(sum(a == b for a, b in zip(actual, expected)), copied)
+        info = json.loads(subprocess.check_output(['ffprobe', '-v', 'error', '-show_entries',
+                                                   'stream=codec_type,start_time', '-of', 'json', str(output)]))
+        self.assertEqual({s['codec_type'] for s in info['streams']}, {'video', 'audio'})
+        self.assertTrue(all(abs(float(s['start_time'])) < 0.03 for s in info['streams']))
+
+    def test_copies_between_keyframes(self):
+        source = self.directory / 'source 日本語.mp4'
+        make_video(source)
+        output, events = self.cut(source, 0.37, 5.62)
+        plan = dict(events)['plan']
+        self.assertEqual((plan['k1'], plan['k2'], plan['body_frames']), (1.0, 5.0, 100))
+        self.assert_exact_clip(output, source, 0.37, 5.62, copied=100)
+
+    def test_matroska_hevc_10_bit_and_ranges_on_keyframes(self):
+        cases = [('matroska.mkv', H264, 0.37, 5.62, 100),
+                 ('hevc.mp4', ('-c:v', 'libx265', '-x265-params',
+                               'keyint=25:min-keyint=25:no-open-gop=1:log-level=error'), 0.37, 5.62, 100),
+                 ('10 bit.mp4', (*H264, '-pix_fmt', 'yuv420p10le'), 0.37, 5.62, 100),
+                 ('on keyframes.mp4', H264, 1, 3, 50),
+                 ('from zero.mp4', H264, 0, 2.3, 50)]
+        for name, codec_args, start, end, copied in cases:
+            with self.subTest(name):
+                source = self.directory / name
+                make_video(source, *codec_args)
+                self.assert_exact_clip(self.cut(source, start, end)[0], source, start, end, copied)
+
+    def test_unsuitable_sources_are_rejected_before_running(self):
+        open_gop = ('-c:v', 'libx265', '-x265-params', 'keyint=25:min-keyint=25:open-gop=1:log-level=error')
+        cases = [('xvid.avi', ('-c:v', 'mpeg4'), 0.37, 5.62, 'unsupported video codec mpeg4'),
+                 ('open gop.mp4', open_gop, 0.37, 5.62, 'fewer than two IDR keyframes'),
+                 ('short.mp4', H264, 1.2, 1.8, 'fewer than two IDR keyframes'),
+                 ('past end.mp4', H264, 1, 9, 'range is outside the source duration')]
+        for name, codec_args, start, end, reason in cases:
+            with self.subTest(name):
+                source = self.directory / name
+                make_video(source, *codec_args)
+                run = Mock()
+                with self.assertRaisesRegex(edgecut.Unsupported, reason):
+                    edgecut.cut(source, start, end, self.directory, run)
+                run.assert_not_called()
+
+    def test_failed_step_or_check_raises(self):
+        source = self.directory / 'source.mp4'
+        make_video(source)
+        with patch('edgecut.mux_command', return_value=['ffmpeg', '-v', 'error', '-i', '/nonexistent', '-f', 'null', '-']):
+            with self.assertRaisesRegex(edgecut.CutFailed, 'mux step exited'):
+                self.cut(source, 0.37, 5.62)
+        with patch('edgecut.verify', side_effect=edgecut.CutFailed('decode errors near a join')):
+            with self.assertRaisesRegex(edgecut.CutFailed, 'decode errors'):
+                self.cut(source, 0.37, 5.62)
+
+    def test_command_line(self):
+        source, output = self.directory / 'source.mp4', self.directory / 'clip.mp4'
+        make_video(source)
+        self.assertEqual(edgecut.main([str(source), '0:00.37', '5.62', str(output)]), 0)
+        self.assert_exact_clip(output, source, 0.37, 5.62, copied=100)
+        with patch('sys.stderr'):
+            self.assertEqual(edgecut.main([str(source), '1.2', '1.8', str(self.directory / 'short.mp4')]), 2)
+        self.assertFalse((self.directory / 'short.mp4').exists())
+
+    def test_parse_time(self):
+        self.assertEqual(edgecut.parse_time('83.5'), 83.5)
+        self.assertEqual(edgecut.parse_time('1:23.5'), 83.5)
+        self.assertEqual(edgecut.parse_time('1:01:23'), 3683)
+        for value in ['-1', '1:60', '1:61:00', 'abc', '1:2:3:4']:
+            with self.assertRaises(Exception):
+                edgecut.parse_time(value)
+
+
+if __name__ == '__main__':
+    unittest.main()