Peach: Local-first video metadata scraper and media manager.
feat(previews): 读取 Roku BIF 索引与 JPEG 预览帧
longmeidao30c172df468c
diff --git a/src/peach/bif.py b/src/peach/bif.pynew file mode 100644index 000000000..4b669c0b9--- /dev/null+++ b/src/peach/bif.py@@ -0,0 +1,130 @@+"""只读 Roku BIF v0 索引,按需读取其中一张 JPEG 预览。"""+from __future__ import annotations++from dataclasses import dataclass+from io import BytesIO+import os+from pathlib import Path+import struct+from typing import BinaryIO++from PIL import Image+++_MAGIC = b"\x89BIF\r\n\x1a\n"+_HEADER_SIZE = 64+_ENTRY = struct.Struct("<II")+_END_TIMESTAMP = 0xFFFFFFFF+_MAX_FRAMES = 1_000_000+_MAX_FRAME_BYTES = 16 * 1024 * 1024+_MAX_FRAME_PIXELS = 16_000_000+++@dataclass(frozen=True)+class BifFrame:+ """一张预览的秒数时间戳、文件绝对偏移和字节长度。"""++ timestamp: float+ offset: int+ length: int+++@dataclass(frozen=True)+class BifIndex:+ """BIF 路径及按时间排列的不可变帧索引。"""++ path: Path+ frames: tuple[BifFrame, ...]+++def _header(stream: BinaryIO, size: int) -> tuple[int, int] | None:+ header = stream.read(_HEADER_SIZE)+ if len(header) != _HEADER_SIZE or header[:8] != _MAGIC:+ return None+ version, count, multiplier = struct.unpack_from("<III", header, 8)+ if version != 0 or any(header[20:]) or count > _MAX_FRAMES:+ return None+ if _HEADER_SIZE + (count + 1) * _ENTRY.size > size or size > _END_TIMESTAMP:+ return None+ return count, multiplier or 1000+++def read_index(path: Path) -> BifIndex | None:+ """读取有界索引;损坏、截断或不支持的文件返回 None。"""+ try:+ with path.open("rb") as stream:+ before = os.fstat(stream.fileno())+ header = _header(stream, before.st_size)+ if header is None:+ return None+ count, multiplier = header+ entries = stream.read((count + 1) * _ENTRY.size)+ if len(entries) != (count + 1) * _ENTRY.size:+ return None+ terminal_timestamp, terminal_offset = _ENTRY.unpack_from(entries, count * _ENTRY.size)+ if terminal_timestamp != _END_TIMESTAMP or terminal_offset != before.st_size:+ return None+ frames = []+ previous_timestamp = -1+ index_end = _HEADER_SIZE + len(entries)+ for number in range(count):+ timestamp, offset = _ENTRY.unpack_from(entries, number * _ENTRY.size)+ _, next_offset = _ENTRY.unpack_from(entries, (number + 1) * _ENTRY.size)+ length = next_offset - offset+ if timestamp == _END_TIMESTAMP or timestamp <= previous_timestamp \+ or offset < index_end or not 0 < length <= _MAX_FRAME_BYTES \+ or next_offset > before.st_size:+ return None+ frames.append(BifFrame(timestamp * multiplier / 1000.0, offset, length))+ previous_timestamp = timestamp+ after = os.fstat(stream.fileno())+ if (before.st_size, before.st_mtime_ns) != (after.st_size, after.st_mtime_ns):+ return None+ return BifIndex(path, tuple(frames))+ except (OSError, ValueError, OverflowError):+ return None+++def read_frame(index: BifIndex, number: int) -> bytes | None:+ """定位并完整验证一张 JPEG;索引失效或图片损坏时返回 None。"""+ if not isinstance(number, int) or not 0 <= number < len(index.frames):+ return None+ frame = index.frames[number]+ if frame.offset < _HEADER_SIZE or not 0 < frame.length <= _MAX_FRAME_BYTES:+ return None+ try:+ with index.path.open("rb") as stream:+ before = os.fstat(stream.fileno())+ header = _header(stream, before.st_size)+ if header is None:+ return None+ count, multiplier = header+ if count != len(index.frames) or frame.offset < _HEADER_SIZE + (count + 1) * _ENTRY.size \+ or frame.offset + frame.length > before.st_size:+ return None+ stream.seek(_HEADER_SIZE + number * _ENTRY.size)+ entries = stream.read(2 * _ENTRY.size)+ if len(entries) != 2 * _ENTRY.size:+ return None+ timestamp, offset, _, next_offset = struct.unpack("<IIII", entries)+ if offset != frame.offset or next_offset - offset != frame.length \+ or timestamp * multiplier / 1000.0 != frame.timestamp:+ return None+ stream.seek(_HEADER_SIZE + count * _ENTRY.size)+ if stream.read(_ENTRY.size) != _ENTRY.pack(_END_TIMESTAMP, before.st_size):+ return None+ stream.seek(frame.offset)+ data = stream.read(frame.length)+ after = os.fstat(stream.fileno())+ if len(data) != frame.length \+ or (before.st_size, before.st_mtime_ns) != (after.st_size, after.st_mtime_ns):+ return None+ if not data.startswith(b"\xff\xd8") or not data.endswith(b"\xff\xd9"):+ return None+ with Image.open(BytesIO(data)) as image:+ if image.format != "JPEG" or image.width * image.height > _MAX_FRAME_PIXELS:+ return None+ image.load()+ return data+ except (OSError, ValueError, OverflowError, Image.DecompressionBombError):+ return Nonediff --git a/tests/test_bif.py b/tests/test_bif.pynew file mode 100644index 000000000..1b9b1eba0--- /dev/null+++ b/tests/test_bif.py@@ -0,0 +1,201 @@+"""Roku BIF v0 的有界索引与 JPEG 随机读取。"""+from io import BytesIO+from pathlib import Path+import struct+import tempfile+import unittest+from unittest import mock++from PIL import Image++from peach import bif+++class BifTests(unittest.TestCase):+ def setUp(self):+ temporary = tempfile.TemporaryDirectory()+ self.addCleanup(temporary.cleanup)+ self.path = Path(temporary.name).resolve() / "预览.bif"+ self.images = []+ for color in ("red", "blue", "green"):+ with BytesIO() as output:+ Image.new("RGB", (8, 8), color).save(output, "JPEG")+ self.images.append(output.getvalue())++ def write_bif(self, *, timestamps=(0, 3, 11), multiplier=1000, padding=b"", images=None):+ images = self.images if images is None else images+ header = b"\x89BIF\r\n\x1a\n" + struct.pack("<III", 0, len(timestamps), multiplier) + bytes(44)+ offset = 64 + 8 * (len(timestamps) + 1) + len(padding)+ entries = []+ for timestamp, image in zip(timestamps, images, strict=True):+ entries.append(struct.pack("<II", timestamp, offset))+ offset += len(image)+ entries.append(struct.pack("<II", 0xFFFFFFFF, offset))+ self.path.write_bytes(header + b"".join(entries) + padding + b"".join(images))++ def change_u32(self, offset, value):+ with self.path.open("r+b") as stream:+ stream.seek(offset)+ stream.write(struct.pack("<I", value))++ def test_nonuniform_timestamps_and_multiplier_units(self):+ for multiplier, expected in ((0, (0., 3., 11.)), (1000, (0., 3., 11.)),+ (10000, (0., 30., 110.)), (250, (0., .75, 2.75))):+ with self.subTest(multiplier=multiplier):+ self.write_bif(multiplier=multiplier)+ index = bif.read_index(self.path)+ self.assertIsNotNone(index)+ self.assertEqual(index.path, self.path)+ self.assertEqual(tuple(frame.timestamp for frame in index.frames), expected)+ self.assertEqual(tuple(frame.length for frame in index.frames), tuple(map(len, self.images)))+ self.assertEqual(bif.read_frame(index, 2), self.images[2])+ self.assertEqual(bif.read_frame(index, 0), self.images[0])++ def test_padding_between_index_and_images_is_supported(self):+ self.write_bif(padding=b"reserved gap")+ index = bif.read_index(self.path)+ self.assertIsNotNone(index)+ self.assertEqual(bif.read_frame(index, 1), self.images[1])++ def test_empty_index_has_only_its_terminal(self):+ self.write_bif(timestamps=(), images=[])+ index = bif.read_index(self.path)+ self.assertEqual(index, bif.BifIndex(self.path, ()))+ self.assertIsNone(bif.read_frame(index, 0))++ def test_index_and_requested_frame_use_bounded_reads(self):+ self.write_bif()+ original_open = Path.open+ reads = []++ def tracking_open(path, *args, **kwargs):+ stream = original_open(path, *args, **kwargs)+ original_read = stream.read++ def read(size=-1):+ self.assertGreaterEqual(size, 0)+ reads.append((stream.tell(), size))+ return original_read(size)++ stream.read = read+ return stream++ with mock.patch.object(Path, "open", tracking_open):+ index = bif.read_index(self.path)+ self.assertIsNotNone(index)+ self.assertEqual(reads, [(0, 64), (64, 32)])+ reads.clear()+ with mock.patch.object(Path, "open", tracking_open):+ self.assertEqual(bif.read_frame(index, 1), self.images[1])+ self.assertEqual(reads, [(0, 64), (72, 16), (88, 8),+ (index.frames[1].offset, len(self.images[1]))])++ def test_missing_file_and_directory_return_none(self):+ self.assertIsNone(bif.read_index(self.path))+ self.assertIsNone(bif.read_index(self.path.parent))++ def test_invalid_magic_version_reserved_and_excessive_count(self):+ for offset, value in ((0, 0), (8, 1), (20, 1), (12, 0xFFFFFFFF)):+ with self.subTest(offset=offset):+ self.write_bif()+ self.change_u32(offset, value)+ self.assertIsNone(bif.read_index(self.path))++ def test_truncated_header_and_table(self):+ for length in (0, 7, 63, 64, 71, 95):+ with self.subTest(length=length):+ self.write_bif()+ data = self.path.read_bytes()+ self.path.write_bytes(data[:length])+ self.assertIsNone(bif.read_index(self.path))++ def test_terminal_timestamp_and_offset_must_match_eof(self):+ for field, value in ((88, 0), (92, 95), (92, 0xFFFFFFFF)):+ with self.subTest(field=field, value=value):+ self.write_bif()+ self.change_u32(field, value)+ self.assertIsNone(bif.read_index(self.path))++ def test_frames_require_increasing_timestamps(self):+ for timestamps in ((0, 0, 1), (3, 2, 4), (0, 1, 0xFFFFFFFF)):+ with self.subTest(timestamps=timestamps):+ self.write_bif(timestamps=timestamps)+ self.assertIsNone(bif.read_index(self.path))++ def test_offsets_must_be_ordered_outside_table_and_inside_file(self):+ for field, value in ((68, 64), (76, 96), (76, 95), (84, 0xFFFFFFFF)):+ with self.subTest(field=field, value=value):+ self.write_bif()+ self.change_u32(field, value)+ self.assertIsNone(bif.read_index(self.path))++ def test_oversized_frame_is_rejected_without_loading_payload(self):+ self.write_bif(timestamps=(0,), images=[self.images[0]])+ eof = 80 + bif._MAX_FRAME_BYTES + 1+ self.change_u32(76, eof)+ with self.path.open("r+b") as stream:+ stream.truncate(eof)+ self.assertIsNone(bif.read_index(self.path))++ def test_frame_number_must_be_in_range(self):+ self.write_bif()+ index = bif.read_index(self.path)+ for number in (-1, 3, 99999, 1.0, "0"):+ with self.subTest(number=number):+ self.assertIsNone(bif.read_frame(index, number))++ def test_corrupt_nonjpeg_and_truncated_jpeg_frames_return_none(self):+ png = BytesIO()+ Image.new("RGB", (8, 8)).save(png, "PNG")+ for payload in (b"invalid", b"\xff\xd8garbage\xff\xd9", self.images[0][:-2],+ self.images[0][:100] + b"\xff\xd9", png.getvalue()):+ with self.subTest(prefix=payload[:12]):+ self.write_bif(timestamps=(0,), images=[payload])+ index = bif.read_index(self.path)+ self.assertIsNotNone(index)+ self.assertIsNone(bif.read_frame(index, 0))++ def test_frame_pixel_budget_is_checked_before_decoding(self):+ self.write_bif()+ index = bif.read_index(self.path)+ with mock.patch.object(bif, "_MAX_FRAME_PIXELS", 32):+ self.assertIsNone(bif.read_frame(index, 0))++ def test_missing_and_truncated_files_invalidate_frame_reads(self):+ self.write_bif()+ index = bif.read_index(self.path)+ with self.path.open("r+b") as stream:+ stream.truncate(index.frames[1].offset)+ self.assertIsNone(bif.read_frame(index, 1))+ self.assertIsNone(bif.read_frame(index, 0))+ self.path.unlink()+ self.assertIsNone(bif.read_frame(index, 0))++ def test_rewritten_index_invalidates_frame_reads(self):+ for field, value in ((8, 1), (12, 2), (16, 10000), (68, 97), (92, 0)):+ with self.subTest(field=field):+ self.write_bif()+ index = bif.read_index(self.path)+ self.change_u32(field, value)+ self.assertIsNone(bif.read_frame(index, 1 if field == 16 else 0))++ def test_forged_frame_bounds_are_rejected(self):+ self.write_bif()+ for offset, length in ((-1, 5), (0, 0), (96, bif._MAX_FRAME_BYTES + 1), (96, 999999)):+ with self.subTest(offset=offset, length=length):+ index = bif.BifIndex(self.path, (bif.BifFrame(0., offset, length),))+ self.assertIsNone(bif.read_frame(index, 0))++ def test_file_changes_during_reads_invalidate_the_result(self):+ self.write_bif()+ index = bif.read_index(self.path)+ original = self.path.stat()+ changed = mock.Mock(st_size=original.st_size, st_mtime_ns=original.st_mtime_ns + 1)+ with mock.patch.object(bif.os, "fstat", side_effect=[original, changed]):+ self.assertIsNone(bif.read_index(self.path))+ with mock.patch.object(bif.os, "fstat", side_effect=[original, changed]):+ self.assertIsNone(bif.read_frame(index, 1))+++if __name__ == "__main__":+ unittest.main()