Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 87 additions & 22 deletions simple_video_utils/chapters.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

import json
from collections.abc import Iterator, Sequence
from dataclasses import asdict, dataclass
from dataclasses import asdict, dataclass, replace
from fractions import Fraction
from itertools import chain, islice, pairwise
from pathlib import Path
Expand Down Expand Up @@ -112,14 +112,19 @@ def write_chapters(
crf: int = 23,
preset: str = "medium",
thread_type: str = "AUTO",
) -> None:
"""Write crops and trims on the source timeline, preserving gaps without encoding filler frames.
trim_to_source: bool = False,
) -> list[ChapterClip]:
"""Write crops and trims on the source timeline, preserving gaps without encoding filler frames, and return the
clips written.

Output must not exist, and a failed write removes it. Coordinates refer to the displayed frame, rotation applied,
as ``video_metadata`` and the frame readers report it, and a rotated source's chapters come out upright.
Each chapter stores its source specification in a JSON ``payload`` tag.
``preset`` is the x264 preset, x264's own by default. ``thread_type`` is PyAV's for decoding the source ("AUTO",
"FRAME", "SLICE" or "NONE"); the frames do not change.
A clip past the last frame the source decodes raises, unless ``trim_to_source``: then it ends at that frame, a
clip starting past it is dropped, and the returned clips, chapters and payloads say so. Headers can count frames
that never decode, and this spares counting them by decoding the source twice.
"""
# clips are checked before the source is decoded or the output created, so a bad clip costs nothing
if not clips:
Expand Down Expand Up @@ -147,18 +152,10 @@ def write_chapters(
if not rate:
message = "Video has no frame rate information"
raise ValueError(message)
chapters = []
for clip in clips:
chapters.append({
"id": len(chapters),
"start": int(clip.start_frame * 1000 / rate + Fraction(1, 2)),
"end": int(clip.end_frame * 1000 / rate + Fraction(1, 2)),
"time_base": Fraction(1, 1000), "metadata": {"payload": json.dumps(asdict(clip))},
})
with open(out, "xb") as file:
try:
with av.open(file, mode="w", format="matroska") as destination:
destination.set_chapters(chapters)
destination.set_chapters(_chapters(clips, rate=rate))
width, height = clips[0].size
# The muxer takes the header (avcC) from the first clip's packets.
track = destination.add_mux_stream("h264", rate=rate, width=width, height=height)
Expand All @@ -167,20 +164,84 @@ def write_chapters(
first = next(decoded, None)
rotation = 0 if first is None else first.rotation % 360
decoded = chain(() if first is None else (first,), decoded)
source_end = 0
for clip in clips:
# shortcut: decodes gaps too; add keyframe seeking if long gaps matter.
frames = islice(decoded, clip.start_frame - source_end, clip.end_frame - source_end)
_write_clip(
stream, track, clip, frames, crf, preset, rate=rate, rotation=rotation,
)
source_end = clip.end_frame
written = _write_clips(
stream, track, clips, decoded, crf, preset, rate=rate, rotation=rotation, trim=trim_to_source,
)
if written != list(clips):
# Matroska writes its chapters in the header, before the frames that showed them wrong
file.flush()
_remux_with_chapters(Path(out), _chapters(written, rate=rate))
except BaseException:
# a trim past the source's end, an unencodable pixel format or an interrupt leaves a truncated MKV,
# which "xb" would then refuse to overwrite on retry
file.close()
Path(out).unlink()
raise
return written


def _write_clips(
source: av.VideoStream,
track: av.VideoStream,
clips: Sequence[ChapterClip],
decoded: Iterator[av.VideoFrame],
crf: int,
preset: str,
rate: Fraction,
rotation: int,
trim: bool,
) -> list[ChapterClip]:
"""Write `clips` from the source's `decoded` frames and return them, trimmed at its end when `trim`."""
written, source_end = [], 0
for clip in clips:
# shortcut: decodes gaps too; add keyframe seeking if long gaps matter.
frames = islice(decoded, clip.start_frame - source_end, clip.end_frame - source_end)
head = list(islice(frames, 1))
if not head and trim:
break
count = _write_clip(
source, track, clip, chain(head, frames), crf, preset, rate=rate, rotation=rotation, strict=not trim,
)
written.append(replace(clip, end_frame=clip.start_frame + count))
if count < clip.end_frame - clip.start_frame:
break
source_end = clip.end_frame
if not written:
message = "every clip starts past the last frame the source decodes"
raise ValueError(message)
return written


def _chapters(clips: Sequence[ChapterClip], rate: Fraction) -> list[dict]:
"""The chapter table of `clips` on the source timeline, each with its source specification as a payload."""
return [
{
"id": index,
"start": int(clip.start_frame * 1000 / rate + Fraction(1, 2)),
"end": int(clip.end_frame * 1000 / rate + Fraction(1, 2)),
"time_base": Fraction(1, 1000), "metadata": {"payload": json.dumps(asdict(clip))},
}
for index, clip in enumerate(clips)
]


def _remux_with_chapters(path: Path, chapters: list[dict]) -> None:
"""Copy `path`'s packets, timestamps kept, into a file with `chapters` that replaces it."""
staged = path.with_name(f"{path.name}.part")
try:
with av.open(str(path)) as source, av.open(str(staged), mode="w", format="matroska") as destination:
destination.set_chapters(chapters)
stream = source.streams.video[0]
track = destination.add_stream_from_template(stream)
for packet in source.demux(stream):
# the demuxer ends with an empty packet that only flushes
if not packet.size:
continue
packet.stream = track
destination.mux(packet)
staged.replace(path)
finally:
staged.unlink(missing_ok=True)



Expand All @@ -200,7 +261,8 @@ def _write_clip(
preset: str,
rate: Fraction,
rotation: int = 0,
) -> None:
strict: bool = True,
) -> int:
graph = av.filter.Graph()
left, top, right, bottom = clip.box
# a rotated source is turned upright first, as FFmpeg autorotates it, then cut like a source stored upright
Expand Down Expand Up @@ -264,7 +326,9 @@ def _write_clip(
encoder.max_b_frames = 0
encoder.options = {"crf": str(crf), "preset": preset}
indices = range(clip.start_frame, clip.end_frame)
for index, frame in zip(indices, frames, strict=True):
count = 0
for index, frame in zip(indices, frames, strict=strict):
count += 1
graph.push(frame)
cropped = graph.pull()
cropped.pts = index
Expand All @@ -276,3 +340,4 @@ def _write_clip(
for packet in encoder.encode():
packet.stream = track
track.container.mux(packet)
return count
31 changes: 31 additions & 0 deletions tests/test_chapters.py
Original file line number Diff line number Diff line change
Expand Up @@ -352,6 +352,37 @@ def test_truncated_trim_raises_instead_of_writing_misleading_chapters(tmp_path):
write_chapters(SOURCE, tmp_path / "short.mkv", [ChapterClip(128, 133, (0, 0, 32, 32))])


def test_trim_to_source_ends_clips_at_the_last_decoded_frame(tmp_path):
source = tmp_path / "source.mkv"
with av.open(str(source), "w") as container:
stream = container.add_stream("ffv1", rate=3)
stream.width, stream.height, stream.pix_fmt = 160, 120, "yuv420p"
for index in range(8):
frame = av.VideoFrame.from_ndarray(np.full((120, 160, 3), index * 20, dtype=np.uint8), format="rgb24")
container.mux(stream.encode(frame))
container.mux(stream.encode())
# the third clip ends past the 8 frames and the fourth starts past them; the sizes change and change back, where
# Matroska demuxes the packets without a dts
clips = [ChapterClip(0, 3, (-16, 32, 32, 80)), ChapterClip(3, 4, (-16, -16, 0, 0)),
ChapterClip(5, 10, (0, 32, 48, 80), payload={"id": 2}), ChapterClip(12, 14, (0, 32, 48, 80))]
output = tmp_path / "trimmed.mkv"
written = write_chapters(source, output, clips, trim_to_source=True)
assert written == [*clips[:2], ChapterClip(5, 8, (0, 32, 48, 80), payload={"id": 2})]
tags = [{key.lower(): value for key, value in chapter["metadata"].items()} for chapter in list_chapters(output)]
assert [json.loads(tag["payload"]) for tag in tags] == [json.loads(json.dumps(asdict(clip))) for clip in written]
with av.open(str(output)) as container:
times = [frame.time for frame in container.decode(video=0)]
assert times == pytest.approx([index / 3 for index in (0, 1, 2, 3, 5, 6, 7)], abs=0.001)
assert [len(list(frames)) for _, _, frames in read_chapters(output)] == [3, 1, 3]
assert sorted(path.name for path in tmp_path.iterdir()) == ["source.mkv", "trimmed.mkv"]


def test_trim_to_source_raises_when_every_clip_starts_past_the_source(tmp_path):
with pytest.raises(ValueError, match="every clip starts past"):
write_chapters(SOURCE, tmp_path / "past.mkv", [ChapterClip(130, 140, (0, 0, 32, 32))], trim_to_source=True)
assert not list(tmp_path.iterdir())


@pytest.mark.parametrize("box", [(-4, 0, 28, 32), (11, 6, 43, 38)])
@pytest.mark.parametrize("pixel_format", ["yuv420p10le", "yuv422p10le"])
def test_cropping_and_padding_preserve_ten_bit_source_precision(tmp_path, box, pixel_format):
Expand Down
Loading