stream.hls: set stream metadata of alternative renditions (EXT-X-MEDIA) when muxing

Checklist

• This is a feature request and not a different kind of issue
• I have read the contribution guidelines
• I have checked the list of open and recently closed feature requests

Collaboration

• My request is genuine and in the best interest of the project
• I will provide feedback should a pull request be opened with a new feature implementation

Description

As a Streamlink user, I would like Streamlink to automatically pass audio track metadata (such as NAME, LANGUAGE, CHANNELS, and disposition flags like DEFAULT/AUTOSELECT) from the HLS master playlist (#EXT-X-MEDIA) to FFmpeg when merging video and audio streams. This ensures that the resulting output file (MKV, MP4, MPEG-TS) contains properly labeled audio tracks with correct language codes and dispositions.

Current Behavior

• Streamlink can merge HLS video and multiple audio tracks using FFmpeg.
• Using --hls-audio-select "*" (or specific languages) correctly includes all selected audio tracks.
• However, metadata from the master playlist is not passed to FFmpeg.
• As a result, the output file lacks track titles, language tags, and default dispositions. Players display generic names like “Audio Track 1/2/3,” which makes it hard to identify the correct track.

Expected Behavior

• Streamlink should extract metadata from #EXT-X-MEDIA entries for TYPE=AUDIO:
  • NAME → Track title (-metadata:s:a:n title=...)
  • LANGUAGE → Language code (-metadata:s:a:n language=...)
  • CHANNELS → Channel info (optional)
  • DEFAULT/AUTOSELECT → Disposition (-disposition:s:a:n default)
• Pass these values to FFmpeg for each audio stream in the correct order.
• Output files should have properly labeled audio tracks, improving usability in media players.

Example CLI

streamlink "https://example/master.m3u8" best \
  --hls-audio-select "*" \
  -o out.mkv
# Expected: Audio tracks in out.mkv have correct title, language, and disposition metadata.

Technical Proposal

• Parse #EXT-X-MEDIA attributes:
  • NAME, LANGUAGE, ASSOC-LANGUAGE, CHANNELS, DEFAULT, AUTOSELECT
• Inject FFmpeg arguments for each audio stream:

-metadata:s:a:<n> title="<NAME>"
-metadata:s:a:<n> language=<LANGUAGE>
-disposition:s:a:<n> default   # if DEFAULT=YES

• Optional new flag for control:
  • --hls-audio-metadata=basic|full|none
    • basic: title, language, default
    • full: includes channels and assoc_language
    • none: disables metadata injection
• Ensure user-specified FFmpeg options override defaults.

Acceptance Criteria

1. All selected audio tracks include correct metadata in MKV/MP4 outputs.
2. Default disposition is applied when DEFAULT=YES.
3. No incorrect or fabricated metadata.
4. Backward compatibility: no breaking changes.

Motivation

• Improves user experience in players (e.g., VLC, Kodi).
• Supports accessibility (audio description, commentary tracks).
• Reduces manual post-processing for archival workflows.

Example FFmpeg Command (internal)

ffmpeg -i video.ts \
  -i audio_de.m3u8 -i audio_en.m3u8 \
  -map 0:v:0 -map 1:a:0 -map 2:a:0 \
  -c copy \
  -metadata:s:a:0 title="Deutsch" -metadata:s:a:0 language=deu -disposition:s:a:0 default \
  -metadata:s:a:1 title="English" -metadata:s:a:1 language=eng \
  out.mkv