Skip to content

armgit / peach

Public Imported from GitHub
0

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.py
new file mode 100644
index 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 None
diff --git a/tests/test_bif.py b/tests/test_bif.py
new file mode 100644
index 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()