Matthew Jackson
7f55271adb
Port + adapt the freemkv native per-picture video index (FVI) from the
old feat/fvi-sink branch onto rc6's codec-agnostic PictureInfo model.
This is a surgical adaptation, not a merge.
Adaptations (fvi_sink.rs, videomap.rs, tests/fvi_pipeline.rs):
- Retarget from the removed crate::mux::codec::mpeg2::PictureInfo (raw
public fields) to rc6's authoritative crate::mux::codec::PictureInfo
in codec/coding.rs, via its accessors.
- type from coding_type() -> CodingType{I,P,B}; emitted for ANY frame
that carries coding (every video codec now fills it), with the
keyframe-flag I/P fallback only when coding is absent.
- Replace the mpeg2-only tff/rff/progressive members with codec-agnostic
members derived through the accessors: field_order (tff/bff/progressive)
and progressive, emitted ONLY when the codec measured the signal
(Option::Some) and omitted otherwise; plus nb_fields.
- Test fixtures rebuilt via PictureInfo::mpeg2(CodingType, Mpeg2Coding{..})
/ coding_type_only(..); added measured_cicp: None to VideoStream
literals for rc6's struct.
Honesty decision (key / random-access):
- The codec-agnostic PictureInfo carries NO GOP-closure (no closed_gop /
gop_start), so key is set from the frame's intra / decode-restart flag
(frame.keyframe == coding.keyframe() for video), NOT a fabricated
clean-RAP claim. The old gop member is honestly omitted. FVI_FORMAT.md
is updated to document this as a limitation: key is an intra picture /
parser-flagged decode-restart point; MPEG-2 open-GOP clean-RAP precision
(closed_gop) is not currently distinguished. §7.1 rewritten for the
new field_order/progressive/nb_fields members.
Wiring:
- mux/mod.rs: pub(crate) mod fvi_sink; pub(crate) mod videomap
(#[allow(dead_code)] on videomap — the VideoMap accumulator is staged
for side-channel reuse, sink builds records directly); pub use
fvi_sink::FviSink.
- mux/resolve.rs: add the fvi:// output scheme to StreamUrl, parse_url,
scheme(), path_str(), input() (write-only reject) and output()
(constructs FviSink), mirroring the mkv:///demux:// patterns.
Provenance fix surfaced by the end-to-end test:
- pipelined_stream::consume_ps was dropping the PS demuxer's byte-exact
source stamp (source: None) when rebuilding PesPacket, so PS/DVD-path
frames reached the mux/index with no provenance (FVI src null). Carry
ps.source through, matching the TS path; the real-pipeline fvi test now
sees the stamped src sectors.
Gate: cargo +1.86 fmt + clippy --lib -D warnings clean; cargo +1.86 test
--lib (2182 passed) and --test fvi_pipeline (2 passed); precommit.sh
libfreemkv green.
libfreemkv Documentation
Technical documentation for libfreemkv, the open source optical drive library.
Start Here
Disc to Rip: End-to-End Flow — How the library goes from a disc in the drive to decrypted content. Read this first.
Reference
| Document | What it covers |
|---|---|
| Architecture | Module map, design principles, error codes, platform support |
| Drive Access | Drive, SCSI transport, profiles, unlock, why raw mode is needed |
| Rip Recovery | Three-layer recovery model: Disc::patch, single-shot Drive::read, DiscStream batch halving |
| AACS Encryption | Key resolution (4 paths), content decryption, bus encryption, SCSI handshake |
| UDF Filesystem | UDF 2.50 with metadata partitions, pointer chain, how files are read from disc |
| MPLS Playlists | Playlist format, play items, STN stream table, coding types |
| CLPI Clip Info | EP map (coarse + fine entries), timestamp-to-sector mapping, extent calculation |
| API Design | Stream API design, PES pipeline, input/output resolution |
Reading Order
If you want to understand the whole library:
- Disc to Rip — the big picture
- Architecture — how modules fit together
- Drive Access — how we talk to hardware
- UDF → MPLS → CLPI — how disc content is structured
- AACS — how encryption works and how we break it
API Documentation
Generated API docs are on docs.rs/libfreemkv.