direct_play_nice 0.1.0-beta.2

CLI program that converts video files to direct-play-compatible formats.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

# Architecture

`direct-play-nice` converts media by separating policy decisions from FFmpeg's
packet loop.

## Conversion Model

1. Runtime configuration is resolved from CLI arguments and optional config.
2. Device profiles are intersected to choose a target container, video codec,
   audio codec, resolution limits, bitrate limits, and H.264 constraints.
3. The input is probed for direct-play compatibility. FFmpeg's detected demuxer
   is the primary container signal; filename extension is used only to
   disambiguate MOV-family containers or as a fallback.
4. Conversion creates an explicit input-to-output stream map. Input stream
   indexes are used only for demuxed packets; output stream indexes are used
   only for encoded packets and muxer metadata.
5. Video, audio, and subtitle streams are decoded, transformed, encoded, and
   muxed through separate stream-processing paths.
6. Optional OCR post-processing handles bitmap subtitles and remuxes generated
   text subtitles into the final output.
7. Post-write verification checks H.264 constraints, and `--validate-output`
   can reopen the final media file to verify expected stream codecs and stream
   hygiene.

## FFmpeg Boundaries

Most FFmpeg operations use rsmpeg wrappers. Raw pointer access is isolated in
small helpers where possible:

- `ffmpeg_ext` contains metadata reads, packet allocation, buffer unref, and
  other narrow unsafe operations.
- `timestamp` contains shared timestamp selection, rescaling, and monotonic DTS
  adjustment.
- `pipeline_streams` owns per-packet video/audio/subtitle processing.
- `pipeline_codec` owns encoder setup and rate/profile options.
- `pipeline_assessment` owns direct-play compatibility explanations.

## Content Policy

Playable A/V streams are preserved by conversion. Attachments, data streams,
and attached pictures are metadata for direct-play targets and are skipped.
Extra video streams are governed by `--unsupported-video-policy`. Text
subtitles are converted when included; bitmap subtitles are deferred to OCR
unless subtitle processing is skipped.

Failures are intentionally policy-driven. Audio setup failures abort because
they would risk invalid audio. Subtitle stream failures follow
`--subtitle-failure-policy`: the default isolates the bad subtitle stream so
A/V conversion can still complete, while strict mode aborts. Hardware encoder
failures may retry with software when a safe fallback is available.