jitsu - the GPAC JIT Server

Introduction

jitsu is a JiT (just-in-time) streaming media packager.

The commercial version supports more input formats (SMIL, ...). It add supports for live inputs, ad-insertion (SCTE-35) and DRMs (Widevine, Playready, FairPlay, ...) and much more. Contact Motion Spell for more information.

Building

cargo build --release
cargo run --release -- -s source.mp4

If you are on Windows using WSL: add export LIBRARY_PATH=/usr/local/lib.

Running

❯ jitsu -h
GPAC Just-In-Time Packager Server

Usage: jitsu [OPTIONS]

Options:
  -p, --port <PORT>      HTTP server port [default: 3000]
  -s, --source <SOURCE>  source URL
      --no-rt            disable realtime mode
  -t, --transcode        enable transcoding
      --no-opts          disable passing options from URL
      --loop <LOOP>.     input loop mode [default: mperiod] [possible values: mperiod, speriod, false]
  -v...                  enable verbose logging -v=jitsu@debug, -vv=jitsu@debug+gpac@info, -vvv=jitsu@trace+gpac@debug
  -h, --help             Print help
  -V, --version          Print version

Loop modes:

• mperiod (default): loop forever and signal a new MPEG-DASH period at each loop.
• speriod: loop forever in a single period (user-provided subtitles are likely to break at loop boundaries because they need timing rewrite).
• false: disable looping input source.

Mixing sources

Using GPAC Playlist Format

By default (--loop mperiod), sources are looped forever.

To compose sources, one can use GPAC's playlists or any GPAC input.

Example to play two files simulteanously, then one file, edit the following .pl playlist:

##begin test.pl
caminandes1_avc_1080p_sdr.mp4 && caminandes1_heaac_64k_eng.mp4 && sub_eng.ttml
audio_video_2.mp4
##end playlist

You can also limit the duration of a source by appending a @ reframer:xs=START:xe=END for each source.

Making Requests

Currently, the request format is as follows:

http://localhost:3000/{arg0}/{arg1}/.../+/{source}/-/{path}

Where {arg0}, {arg1}, etc. are options set on the sink filter. The /-/ is a delimiter that separates the sink options from the actual media path. {path} is the path to the media file you want to access. We needed to use / because the usual ?and & query parameters may not be propagated to the server queries. The + is a delimiter that separates the sink options from the source path. {source} is the path to the source file. If not specified, the source provided at server launch will be used.

The sink filter is the dasher filter for both DASH (.mpd extension) and HLS (.m3u8 extension). The documentation can be accessed online or via the command-line (gpac -hh dasher for the most complete documentation).

For example, a request might look like this:

http://localhost:3000/segdur=2/profile=live/cmaf=cmf2/stl=true/-/out.m3u8

Or this:

http://localhost:3000/segdur=2/profile=live/cmaf=cmf2/stl=true/+/beepbop.mp4/-/out.m3u8

It is possible to escape characters. Here is a more complex example:

http://localhost:3000//segdur=3.84/spd=8000/tsb=240/ast=1735689600/utcs=https%3A%2F%2Ftime.akamai.com%2F%3Fiso%26ms/live/cmf2/stl=true/-/out.mpd

Since the manifest name has influence on the sink behavior, if this task is going to be the first one then the first request should be for the manifest itself.

Rewriting subtitles timing

In looping modes (mperiod and speriod), sources are looped forever. When the source contains subtitles, subtitle timings need to be both segmented and adjusted at each loop. This is achieved by introducing a new Period when looping. In the rare event where your subtitle content doesn't need to be segmented and your source doesn't loop (--loop false), you can safely ignore this section. The speriod mode keeps a single period across loops but user-provided subtitles may break at loop boundaries.

Subtitle timing rewrite only works with raw subtitles (i.e. .ttml or .vtt inputs, not .mp4). To trigger subtitle segmentation and rewrite, the ttml_agg argument (see previous section about sink filter options) must be added.

Debugging

You can adjust logs and display the processing graph with export RUST_LOG=debug (possible values: trace, debug, info, warn, and error).

Implementation details

The repository is composed of two main components:

• app: A Rust-based HTTP server (powered by Axum) that handles incoming requests, manages tasks, and serves data.
• libs/gpac-sys: Contains C++ bridge to organize GFIO and GPAC session management. cxx crate is used to facilitate safe interoperation between Rust and C++.

The reason for this structure is to separate the server logic from the low-level GPAC handling. Therefore anything related to GPAC would be exclusively handled with the C++ bridge located in libs/gpac-sys/{bridge/include}.

Known Issues

• Sporadically, QuickJS throws an assertion which crashes the server. The exact cause is unknown.

License

This application is dual-licensed AGPL or commercial. Contact Motion Spell for more information.

Acknowledgements

This work was partly sponsored by DVB.