Shaka Packager Documentation

Shaka Packager supports template-based segment URL construction following ISO/IEC 23009-1:2014. You can use specific identifiers enclosed in $ characters to dynamically construct segment URLs. Identifier matching is case-sensitive.

Supported Identifiers

Note: You can use either $Number$ or $Time$, but not both in the same template. $RepresentationID$ and $Bandwidth$ are currently not supported.

Formatting with printf-style tags

Identifiers can be suffixed with a format tag inside the enclosing $ characters using the prototype %0[width]d. The width parameter is an unsigned integer specifying the minimum number of characters. If the value is shorter than the width, it is padded with zeros. Values are not truncated if they exceed the width.

Example syntax: $Number$%04d (will result in 4-digit zero-padded numbers like 0001).

Shaka Packager uses the ContentKeyUsageRuleList within the CPIX document to determine which keys apply to which streams:

• Track Type Mapping: Rules with an intendedTrackType attribute map keys to streams where the DRM label matches the attribute (e.g., AUDIO, SD, HD, UHD1, UHD2).
• Audio Filtering: Rules with an AudioFilter map keys specifically to audio streams.
• Video Filtering: Rules with VideoFilter pixel ranges map keys to video labels (SD/HD/UHD1/UHD2) based on the thresholds defined by --max_sd_pixels, --max_hd_pixels, and --max_uhd1_pixels.
• Combined Constraints: If both intendedTrackType and a filter are present, the stream must satisfy both.
• Default Mapping: A rule with no filters, or a document containing a single key and no usage rules, maps that key to all streams.
• Unused Keys: Keys not referenced by any usage rule are ignored.

Note: DRM signaling is derived from the document's DRMSystemList and is authoritative. Key rotation via --crypto_period_duration is not supported when using CPIX.

Because Teletext subtitles are 'sparse' (data only exists when text is displayed), Shaka Packager uses a 'heartbeat' mechanism to ensure continuous text segments and proper alignment with video segments. This mechanism is automatic when processing MPEG-TS files containing both video and teletext streams.

To control the timing offset between video timestamps and text segment generation, use the --ts_ttx_heartbeat_shift parameter.

• Default: 90000 (at 90kHz timescale, equivalent to 1 second).
• When to increase: If text segments are generated too late (later than video segments).
• When to decrease: If some text cues are missing from the output.

Note: For best results and automatic segment alignment, always include the video and teletext streams from the same MPEG-TS source in the same packager invocation.

# Example with custom heartbeat shift (3 seconds)
$ packager \
  --ts_ttx_heartbeat_shift 270000 \
  'in=input.ts,stream=video,init_segment=v/init.mp4,segment_template=v/$Number$.m4s' \
  'in=input.ts,stream=audio,init_segment=a/init.mp4,segment_template=a/$Number$.m4s' \
  'in=input.ts,stream=text,cc_index=888,lang=en,init_segment=t/init.mp4,segment_template=t/$Number$.m4s'

When processing MPEG-TS input with DVB-Teletext, Shaka Packager uses a specialized pipeline to ensure text segments align perfectly with video/audio segment boundaries. This is achieved through a coordination mechanism:

1. Mp2tMediaParser: Provides a "heartbeat" (video PTS timestamps) to the teletext parser to drive segment generation even when no subtitle data is present.
2. EsParserTeletext: Parses DVB-Teletext PES packets and emits samples with roles like CueStart, CueEnd, TextHeartBeat, and MediaHeartBeat.
3. SegmentCoordinator: Acts as an N-to-N handler. It replicates SegmentInfo from the video/audio streams to the teletext streams. This ensures that the text segment boundaries match the video segment boundaries exactly.
4. TextChunker: In "coordinator mode", it uses the SegmentInfo events received from the SegmentCoordinator to determine segment boundaries, rather than relying on the timestamps within the text samples themselves.