ms — Manual & Reference

01

Quick Start

Installation

# macOS / Linux
git clone https://github.com/mediastream-framework/mediastream-framework.git
cd mediastream-framework
cargo build --release
cp target/release/ms /usr/local/bin/ms

# Verify
ms --version
ms hw

First Steps

ms probe movie.mp4         # Inspect any media file
ms encode in.mp4 out.av1   # Encode to AV1
ms hw                       # Detect GPU hardware
ms codecs                   # List supported codecs
ms validate suspect.mp4    # Security scan
ms debug --text             # Full diagnostic dump

02

System Commands

ms probe <FILE>

Inspect any media file. Returns format, duration, resolution, codecs, bitrate, audio channels.

ms probe movie.mp4
ms probe song.flac
ms -v probe movie.mp4          # Verbose output

ms hw

Auto-detect GPU hardware: Apple M1-M4, NVIDIA NVENC/NVDEC, Intel Arc/QSV, AMD VCN.

ms hw
ms --verbose hw

ms codecs [--cutting-edge]

List all supported codecs — 29 general + 19 audio. --cutting-edge shows experimental codecs.

ms codecs
ms codecs --cutting-edge

ms filters

List all 38 video filters by category (geometric, color, temporal, compositing).

ms filters

ms backends

Show available decode/encode backends and their status.

ms backends
ms --use oxideav encode in.mp4 out.av1
ms --use rff encode in.mp4 out.av1

ms debug [FILE] [--text]

Full diagnostic dump — system info, hardware detection, codec registry, file probe, memory status.

ms debug
ms debug --text
ms debug movie.mp4 --text

ms magic

Magic bytes identification — 47 rules covering 31 formats. Identifies files by header bytes.

ms magic
ms magic | grep mp4

ms list [DIR]

List directory contents with media info (format, duration, resolution).

ms list
ms list ~/Videos

03

Encode

ms encode <INPUT> <OUTPUT> [OPTIONS]

Encode video to AV1 with built-in filters. rav1e encoder — pure Rust, no C.

Flag	Description
`--chunk-size N`	Process N frames per chunk (default: 30)
`--crop WxH+X+Y`	Crop before encoding
`--scale WxH`	Scale before encoding
`--rotate DEG`	Rotate 90, 180, or 270 degrees
`--speed FACTOR`	Playback speed (0.5 = half, 2.0 = double)
`--trim-start SECS`	Start time in seconds
`--trim-end SECS`	End time in seconds
`--cores N`	Number of CPU cores to use

ms encode input.mp4 output.av1
ms encode input.mp4 output.av1 --chunk-size 30
ms encode input.mp4 output.av1 --crop 320x240+0+0 --scale 640x480
ms encode input.mp4 output.av1 --cores 5
ms encode input.mp4 output.av1 --trim-start 10 --trim-end 30

04

Video Operations

ms video <INPUT> <OP> <OUTPUT> [ARGS]

Video manipulation operations — all output to AV1 MP4.

Operation	Args	Description
`crop`	X Y W H	Crop to rectangle at position (X,Y) with size WxH
`scale`	W H	Scale to exact dimensions
`rotate`	DEG	Rotate 90, 180, or 270 degrees
`trim`	--start S --end E	Extract clip from S to E seconds
`speed`	--factor F	Change playback speed (0.5–4.0)
`concat`	-i FILE2	Concatenate multiple clips
`overlay`	--main M --overlay O	Picture-in-picture overlay

ms video in.mp4 crop out.mp4 0 0 640 480
ms video in.mp4 scale out.mp4 1280 720
ms video in.mp4 speed --factor 2.0 out.mp4
ms video clip1.mp4 concat out.mp4 -i clip2.mp4
ms video in.mp4 trim out.mp4 --start 10 --end 20

05

Audio Processing

ms audio <INPUT> <OP> [OUTPUT] [OPTIONS]

Decode, resample, encode, normalize, fade, speed, pitch shift. Opus encode with auto-resample. AAC multichannel decode via fdk-aac-rust.

Operation	Args	Description
`info`	—	Show audio metadata (no output file)
`decode`	OUTPUT	Decode to WAV
`opus-encode`	--bitrate B OUTPUT	Encode to Opus (auto-resample to 48kHz)
`resample`	--rate R OUTPUT	Resample to target sample rate
`normalize`	OUTPUT	Normalize audio levels
`fade`	--in S --out S OUTPUT	Apply fade in/out
`speed`	--factor F OUTPUT	Change playback speed
`pitch`	--semitones N OUTPUT	Pitch shift by N semitones

ms audio song.mp3 info
ms audio song.mp3 decode song.wav
ms audio song.wav opus-encode --bitrate 128000 song.opus
ms audio song.wav resample --rate 48000 out.wav
ms audio song.wav normalize normalized.wav
ms audio song.wav fade --in 2 --out 3 faded.wav

06

Image Processing

ms image <INPUT> <OP> [ARGS] OUTPUT

Resize, crop, rotate, flip, thumbnail. Auto-detects JPEG, PNG, WebP, BMP, TIFF, GIF.

ms image photo.jpg resize 1920 1080 out.jpg
ms image photo.jpg crop 100 200 800 600 cropped.jpg
ms image photo.jpg rotate 90 rotated.jpg
ms image photo.jpg flip -d vertical flipped.jpg
ms image photo.jpg thumb 256 thumb.jpg

07

Container Operations

ms mux / ms demux

Mux separate audio + video into a container, or extract streams from a container. No re-encoding.

# Mux
ms mux out.mp4 -v video.h264 -a audio.wav
ms mux out.mp4 -v video.mp4 -a music.opus

# Demux
ms demux movie.mp4 --video out.h264 --audio out.aac
ms demux movie.mp4 --video only_video.h264

08

Security

ms validate <FILE> [--json]

Security scanner — detects PHP disguises, polyglot files, embedded scripts, ID3 bombs, EXIF injection, MP4 atom overflow, MKV EBML recursion.

ms validate suspect.mp4
ms validate --json suspect.php.jpg

ms sanitize <INPUT> OUTPUT [--json]

Strip all metadata, hidden atoms, ID3 tags, EXIF data. Keeps only essential video + audio streams.

ms sanitize infected.mp4 clean.mp4
ms sanitize photo.jpg clean.jpg
ms sanitize track.mp3 clean.mp3

ms drm <INPUT> OUTPUT --action ACTION

AES-128-CTR encryption/decryption. Key files generated alongside output. HMAC-SHA256 token signing for PPV.

ms drm movie.mkv enc.mkv --action encrypt
ms drm enc.mkv dec.mkv --action decrypt

ms ppv-create / ms ppv-play

Pay-per-view system — create self-destructing video packages with max views, expiry, and token verification.

ms ppv-create movie.mkv pkg.mkv --max-views 5
ms ppv-create movie.mkv pkg.mkv -n 3 -d 3600
ms ppv-play encrypted.mkv decrypted.mkv --token abc123

09

Streaming & Broadcast

ms streaming <PROTOCOL> <INPUT> [OUTPUT] [OPTIONS]

HLS segmentation, MoQ/QUIC transport, WHIP/WHEP WebRTC, SRT, RTMP, DASH.

# HLS
ms streaming hls input.mp4 hls/ --segment-duration 4

# fMP4/CMAF
ms streaming hls input.mp4 hls/ --format fmp4

# Show all protocols
ms streaming protocols

ms broadcast <TYPE> [OPTIONS]

NMOS IS-04/IS-05 registry, SMPTE ST 2110 transport, IPMX device integration.

ms broadcast nmos
ms broadcast st2110 --interface eth0
ms broadcast features

10

Pipeline & Queue

ms pipeline <INPUT> --steps '[...]'

Chain operations with JSON pipelines. Auto context passing between steps. Fork/join support.

ms pipeline in.mp4 --steps '[
  {"name":"scale","operation":"scale","params":{"width":640,"height":480}},
  {"name":"encode","operation":"encode","params":{"codec":"av1"}}
]'

ms queue <ACTION> [OPTIONS]

Background job queue — Unix socket IPC, sequential processing, daemon mode.

ms queue start --daemon
ms queue submit encode in.mp4 out.av1
ms queue status
ms queue stop

11

Global Flags

Flag	Description
`-v, --verbose`	Enable verbose output
`--json`	Output as JSON
`--text`	Output as plain text
`--use BACKEND`	Select decode/encode backend (mstream, oxideav, rff)
`--features LIST`	Enable feature flags

msManual