Skip to content

Container: add Matroska (MKV) demuxer for existing supported codecs - #21

Draft
Nathan-Nascimento-Mendes wants to merge 1 commit into
NathanNeurotic:masterfrom
Nathan-Nascimento-Mendes:feature/mkv-container
Draft

Container: add Matroska (MKV) demuxer for existing supported codecs#21
Nathan-Nascimento-Mendes wants to merge 1 commit into
NathanNeurotic:masterfrom
Nathan-Nascimento-Mendes:feature/mkv-container

Conversation

@Nathan-Nascimento-Mendes

Copy link
Copy Markdown

Important

Author note: This PR was developed with AI assistance (DeepMind Antigravity) by a developer who does not normally work with C, embedded systems, or PS2 assembly. A thorough review, feedback, and verification from maintainers would be greatly appreciated!

Pull Request

Summary

Adds a native Matroska / MKV (.mkv) container demuxer to Simple Media System (SMS).

  • What does this PR do?: Allows SMS to detect, probe, demux, and play .mkv media files containing video, audio, and subtitle streams that SMS already natively supports.
  • Scope limitation: This adds a container demuxer only; it does not introduce new video decoders (e.g. H.264/AVC, HEVC, VP9, or AV1).
  • Why is it necessary?: Many users have multimedia files in Matroska containers; this enables playback without needing to remux into AVI or MP4 when compatible codecs are already present.

Type of Change

  • Feature addition
  • Bug fix
  • Performance improvement
  • Refactor (non-functional change)
  • Documentation update
  • Breaking change
  • Other (explain below)

Related Issues

Related to #18


Scope

  • This PR contains a single logical change.
  • No unrelated refactoring is included.
  • No formatting-only noise is included.

Technical Details

  • EBML Parser: Implements safe parsing for Element IDs (1–4 bytes), VINTs (1–8 bytes), IEEE-754 floats, UTF-8 strings, and unknown element skipping without losing stream alignment.
  • Codec Mapping & Fallback:
    • Video: V_MPEG4/ISO/ASP, V_MPEG1, V_MPEG2, V_MS/VFW/FOURCC (via BITMAPINFOHEADER).
    • Audio: A_AAC (extracting AudioSpecificConfig from CodecPrivate), A_MPEG/L3, A_MPEG/L2, A_AC3, A_DTS, A_VORBIS, A_FLAC, A_PCM/INT/LIT, A_PCM/INT/BIG, A_MS/ACM.
    • Subtitles: S_TEXT/UTF8, S_TEXT/ASCII.
    • Graceful fallback: Incompatible streams (e.g. H.264 video) are ignored without failing global probing if compatible streams exist.
  • Packet Demuxing & Lacing: Supports SimpleBlock and BlockGroup keyframe detection, and unlaces No-lacing, Xiph, Fixed-size, and EBML laced frames.
  • Cues & Seeking: Parses Cues index for binary-search seek to the nearest keyframe cluster.
  • Multi-Track: Publishes compatible audio and subtitle streams (up to SMS_MAX_STREAMS = 8) with language tags for dynamic OSD switching.
  • Makefile: Added SMS_ContainerMKV.o and set EE_CFLAGS to -G4096 to safely accommodate the GP-relative small data section.

Testing

  • Builds successfully
  • No new warnings introduced
  • Existing functionality tested
  • Regression risk evaluated
  • Tested on latest default branch

How it was tested:

  • Executed unit test suite (tools/test_mkv_demuxer.py) covering VINT encoding/decoding, multi-track MKV demuxing, lacing unpacking, Cues seek, and corrupted file rejection.
  • Successfully built and packed clean binaries (SMS.elf and SMS-packed.elf) using the official ps2dev/ps2dev:v1.0 toolchain container.

Breaking Changes

No breaking changes.


Security Considerations

  • File handling: Bounded buffer reads, safe size checks, and validated string/allocation lengths prevent memory corruption from malformed or hostile EBML files.

Checklist

  • I have read CONTRIBUTING.md
  • I have followed the project code standards
  • I have rebased on the latest default branch
  • CI passes locally or via GitHub
  • This PR does not introduce hidden side effects

Additional Notes

Future work can expand on this foundation to support remote HTTP streaming (Part B of the SMS roadmap).

Adds MKV container demuxing support for formats already supported by SMS (MPEG-4 Part 2 / Xvid, MPEG-1/2, AAC, MP3, AC3, DTS, Vorbis, FLAC, PCM, and UTF-8 subtitles).

- Implements EBML parsing, track mapping, and lacing (Xiph, Fixed, EBML).

- Supports keyframe seeking via Cues and multi-audio/subtitle OSD switching.

- Gracefully ignores unsupported codecs (e.g. H.264/HEVC) without failing.

- Registers .mkv in file/container tables and updates Makefile.
@coderabbitai

coderabbitai Bot commented Aug 20, 2026

Copy link
Copy Markdown

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: c475d140-fbcc-4f3c-8261-f1af386f6361

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@NathanNeurotic

Copy link
Copy Markdown
Owner

@Nathan-Nascimento-Mendes please do real hardware testing and report back.
As an avid AI user myself, I need some human testing verification.
Please report back, artifacts are here:
https://github.com/NathanNeurotic/Simple-Media-System/actions/runs/32332469723
https://github.com/NathanNeurotic/Simple-Media-System/actions/runs/32332469722

@Nathan-Nascimento-Mendes

Copy link
Copy Markdown
Author

@NathanNeurotic

Copy link
Copy Markdown
Owner

No problem at all! I appologize I figured the draft was a request hahaha
I am all for experimentation - do not apologize! Thank you for taking time to consider contributing <3

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants