MSEngine
& MSPlayer

MSPlayer (Browser)                     Serve.py (Python)                    MSEngine (Rust)
┌──────────────┐                      ┌──────────────┐                     ┌──────────────┐
│  loadURL()   │──── GET /api/probe ──▶│  _ms_json()  │──── ms probe ─────▶│  probe.rs    │
│              │◀─── JSON result ─────│              │◀─── JSON result ───│  MKV parser  │
│              │                      │              │                     │  EBML walker │
│  auto-detect │──── POST /api/      │              │                     │              │
│  unsupported │     transcode ──────▶│  _handle_    │──── ms encode ────▶│  decode +    │
│  format      │◀─── {url, method} ──│  transcode() │◀─── MP4 output ───│  re-encode   │
│              │                      │              │                     │              │
│  video.src   │──── GET /api/       │              │                     │              │
│  = mp4 url   │     uploads/... ───▶│  file serve  │                     │              │
└──────────────┘                      └──────────────┘                     └──────────────┘

FORMAT   OFFSET  HEADER BYTES                          DESCRIPTION
───────  ──────  ──────────────────────────────────────  ─────────────────────────────────
mp4      4       [66747970]                             ISO Base Media (MP4/MOV/M4V/3GP)
mkv      0       [1a45dfa3]                             Matroska (MKV/WebM)
wav      0+8     [52494646] + [57415645]                WAV (RIFF WAVE)
flac     0       [664c6143]                             FLAC lossless audio
ogg      0       [4f676753]                             OGG container (Vorbis/Opus)
mp3      0       [494433] or [ff e0] (sync word)        MP3 (ID3v2 or MPEG sync)
jpeg     0       [ffd8ff]                               JPEG (SOI marker)
png      0       [89504e47 0d0a1a0a]                    PNG (8-byte signature)
y4m      0       [595556344d504547]                     YUV4MPEG2 raw frames
ts       0       [47]                                   MPEG-TS (sync byte)
yuv      ext     (no header)                            Raw YUV video (extension only)

// Initialize
const player = new MSPlayer(document.getElementById('root'), {
  type: 'video',       // 'video' | 'audio'
  apiBase: ''          // API base URL
});

// Load from server
await player.loadURL('/api/media/test.mp4', 'test.mp4');

// Load local file (drag & drop or file picker)
// Handled automatically by the player

// Probe file
const info = await player.probe('test.mp4');
// Returns: { duration, size, format, width, height, video, audio }

// Security scan
const result = await player.validate('test.mp4');
// Returns: { threats, score, details }

// Generate HLS
const hls = await player.generateHLS('test.mp4', 4);
// Returns: { playlist, segments, stderr, exit }

# Generate HLS with 4-second segments
ms streaming hls input.mp4 output_dir/ --segment-duration 4

# Output:
# output_dir/
#   ├── index.m3u8          # Master playlist
#   ├── segment_000.ts      # TS segment (PAT/PMT/PES)
#   ├── segment_001.ts
#   └── ...

# Start queue daemon
ms queue start --socket ~/.mediastream/engine.sock

# Submit job
ms queue submit --input video.mp4 --operation encode --output out.mp4

# Check status
ms queue status

# Stop daemon
ms queue stop

// Required: MKV EBML Demuxer for H.264/H.265
//
// 1. Parse EBML Header (magic: 1A 45 DF A3)
//    └── EBMLRead (element size encoding: VINT)
//
// 2. Parse Segment
//    ├── Tracks
//    │   └── TrackEntry
//    │       ├── TrackType = 1 (video)
//    │       ├── CodecID = "V_MPEG4/ISO/AVC"
//    │       └── CodecPrivate = AVCDecoderConfigurationRecord
//    │           ├── lengthSizeMinusOne = 3 (4-byte NALU lengths)
//    │           ├── SPS[] (extract, prepend 00 00 00 01)
//    │           └── PPS[] (extract, prepend 00 00 00 01)
//    │
//    └── Cluster
//        ├── Timestamp (relative to segment start)
//        └── SimpleBlock
//            ├── TrackNumber (varint)
//            ├── Timestamp (signed 16-bit, relative to Cluster)
//            ├── Flags (keyframe = bit 7)
//            └── Data (length-prefixed NALUs)
//                ├── 4-byte length + NALU (SPS/PPS/IDR/P-frame)
//                ├── 4-byte length + NALU
//                └── ...
//
// 3. Convert to Annex B
//    For each SimpleBlock on video track:
//    ├── If keyframe: emit SPS + PPS (from CodecPrivate) with start codes
//    └── For each NALU in block data:
//        ├── Read 4-byte length N
//        ├── Write 00 00 00 01
//        └── Write N bytes of NALU data
//
// 4. Feed Annex B stream to existing decoders:
//    ├── H.264: mstream_h264::decoder::Decoder::decode_nal()
//    └── AV1: rav1d decoder (via OBU extraction)