Media over QUIC (MoQ)

This tutorial explains how to use Shaka Player to stream live content over MoQT (Media over QUIC Transport), using the MSF (MoQ Streaming Format) manifest parser built into the player.

Important

Support for MoQ in Shaka Player is currently experimental and is only available in the experimental builds. It will remain experimental until the underlying specifications are finalized and no longer in draft status.

Relevant specs:

• draft-ietf-moq-transport
• draft-ietf-moq-msf
• draft-ietf-moq-cmsf

Prerequisites

MoQ streaming relies on the WebTransport browser API, which has the following requirements:

• The page must be served over HTTPS or from localhost.
• The browser must support the WebTransport API.
• The MoQT relay/server must also be reachable over HTTPS (or from localhost for testing with self-signed certificates; see fingerprintUri below).

Basic Usage

Loading a MoQ stream is straightforward, but there is one mandatory requirement: you must always pass 'application/msf' as the mimeType argument to player.load(). This is what tells Shaka to use the MSF manifest parser instead of DASH or HLS parsers.

const manifestUri = 'https://relay.example.com/moq-endpoint';

async function initPlayer() {
  shaka.polyfill.installAll();

  if (!shaka.Player.isBrowserSupported()) {
    console.error('Browser not supported!');
    return;
  }

  const video = document.getElementById('video');
  const player = new shaka.Player();
  await player.attach(video);

  player.addEventListener('error', (event) => {
    console.error('Error code', event.detail.code, event.detail);
  });

  try {
    // The mimeType 'application/msf' is REQUIRED for MOQ streams.
    await player.load(manifestUri, /* startTime= */ null, 'application/msf');
    console.log('MOQ stream loaded!');
  } catch (e) {
    console.error('Load failed', e);
  }
}

document.addEventListener('DOMContentLoaded', initPlayer);

Important: Never omit the 'application/msf' MIME type. Without it, Shaka cannot identify the stream as a MoQ source and will fail or attempt to parse it as a different format.

What Happens Under the Hood

When player.load() is called with 'application/msf', Shaka:

1. Opens a WebTransport connection to the given URI.
2. Performs MoQT session setup (client/server handshake, version negotiation).
3. Either subscribes to the catalog track in a known namespace (if manifest.msf.namespaces is configured), or waits for a PUBLISH_NAMESPACE announcement from the server to discover the namespace dynamically.
4. Parses the catalog (a JSON document) to discover all available audio, video, and text tracks.
5. Subscribes to each track's MoQT data stream, feeding segments into Shaka's regular media pipeline.

Note: Only live content is supported. VOD content (where isLive is false in the catalog) is not supported and will throw an error.

By default a presentation has no DVR window: the seek range is a few seconds around the live edge, because nothing in the catalog says where to subscribe from to get anything older. A publisher that supplies a media timeline lifts that restriction; see Media timeline, DVR and seeking.

Supported Packagings

Each catalog track declares how its media is packaged into MoQT objects, in its packaging field. A track whose packaging Shaka does not support is skipped, and the rest of the catalog still plays.

MPEG-2 Transport Stream (m2ts)

Both source packet sizes are supported: 188-octet transport packets and 192-octet M2TS source packets, whose 4-octet arrival timestamp is discarded because it says nothing about presentation.

Two things are worth knowing about this packaging:

• The track must declare codec. The codec decides which source buffers MediaSource opens, and that happens before the first group has arrived to be inspected, so it cannot be discovered from the media. A track carrying a muxed program lists both codecs, comma separated, exactly like the HLS CODECS attribute:

  {
    "name": "program-1-ts",
    "packaging": "m2ts",
    "codec": "avc1.64001f,mp4a.40.2",
    "m2tsPacketSize": 188,
    "m2tsPcrPid": 257
  }
  

  Shaka opens an audio and a video source buffer from that one track and feeds both from its segments.

• Latency is one Group. A transport packet carries no timing of its own, a PES packet spans many of them, and an object boundary falls wherever the publisher chose to cut, so a single object cannot be appended on its own. The Group is the smallest unit that can be, and it is only complete once the next one starts. Expect higher latency than chunk-per-object, where each object can be appended the moment it arrives.

Declaring initData (base64 PAT/PMT packets) is recommended: Shaka prepends it to every group, which is what keeps a stream playable when its program information does not repeat at the start of each group.

If the publisher signals a PCR discontinuity between two groups, Shaka re-anchors the media so that presentation time keeps running forward, and tells the transmuxer to start a fresh initialization segment.

Note: m2ts needs the transmuxer, which is a separate build target. A custom build must include +@transmuxer alongside +@msf. The same is true of HLS with transport stream segments.

Media timeline, DVR and seeking

MoQT addresses content by Group and Object, while media is addressed by presentation time, and nothing in the transport relates the two. A player that does not know the relation can only ever ask for the live edge: a time the viewer seeks to names no Location to subscribe from. The media timeline (draft-ietf-moq-msf section 7) is what supplies it, and with it the seek range stops being "whatever has already arrived".

MSF carries the relation two ways, and Shaka reads both. Where they describe the same time, the explicit records win, because they are observations of what was published while a template is a prediction.

An explicit media timeline track

A track with "packaging": "mediatimeline" publishes JSON documents listing one record per published Group: the media presentation timestamp in milliseconds, the Location as [Group ID, Object ID], and the wallclock time of encoding in milliseconds since the epoch (0 when it is not known). Its depends field names the tracks the records address, and is required.

{
  "name": "history",
  "packaging": "mediatimeline",
  "mimeType": "application/json",
  "depends": ["video0", "audio0"]
}

[
  [0, [0, 0], 1759924158381],
  [2002, [1, 0], 1759924160383],
  [4004, [2, 0], 1759924162385]
]

The first Object of each Group carries everything the publisher still offers, so a record missing from it has aged out and leaves the seek range; the Objects after it in that Group carry only what is new.

A template

Where Groups have a constant duration, a media track can carry the relation inline instead, as [startMediaTime, deltaMediaTime, startLocation, deltaLocation, startWallclock, deltaWallclock]:

{
  "name": "video0",
  "packaging": "loc",
  "codec": "av01.0.08M.10.0.110.09",
  "template": [0, 2002, [0, 0], [1, 0], 1759924158381, 2002]
}

Each entry is then start + n * delta, so the template describes any point of the presentation without listing it. A track with a template should not also have a timeline track, and the template must not change once publishing has started.

What Shaka does with it

• The seek range reaches back to the oldest point the timeline describes, instead of sitting at the live edge. It is only offered when every subscribed track has a timeline: a range that only half the media can be served for is a stall, not a seek. manifest.availabilityWindowOverride still overrides it.
• Seeking behind the live edge withdraws each track's subscription and asks for it again from the Location the timeline gives for the target, which is what a seek costs on a transport where a subscription is a position in a track rather than a URL to fetch. Seeking within what has already arrived costs nothing, and seeking back to the live edge returns the subscriptions to following it.

Every supported draft can subscribe from a past Location, though each carries the request differently: draft-14 as fields of the SUBSCRIBE message, draft-16 and draft-18 in the SUBSCRIPTION_FILTER parameter, draft-20 and draft-21 in LOCATION_FILTER.

Note: A media timeline describes what the publisher offered when the timeline was written, and a publisher may still refuse to start where it says, typically because the Group is older than anything it still holds. When that happens the track returns to the live edge rather than waiting for media that is not coming.

Compressed timeline documents (MSF_COMPRESSION) are not supported yet and are discarded.

MSF Configuration

All MoQ-specific options live under manifest.msf in the player configuration.

player.configure({
  manifest: {
    msf: {
      // Options described below
    }
  }
});

fingerprintUri (string, default: '')

URL of a plain-text file containing the SHA-256 hex fingerprint of the server's self-signed TLS certificate. This is needed when connecting to a local relay or a server with a self-signed cert that the browser would otherwise reject.

player.configure({
  manifest: {
    msf: {
      fingerprintUri: 'https://relay.example.com/cert.hex',
    }
  }
});

When set, Shaka fetches the fingerprint before opening the WebTransport connection and uses it to pin the certificate. Leave empty for servers with a CA-signed certificate.

namespaces (Array<string>, default: [])

The MoQT namespace to subscribe to for the catalog track. A namespace is an array of string path components that together identify the session on the relay.

player.configure({
  manifest: {
    msf: {
      // Subscribe to the catalog in namespace ['live', 'channel1']
      namespaces: ['live', 'channel1'],
    }
  }
});

When namespaces is set, Shaka immediately subscribes (or fetches) the catalog in that namespace. When left empty ([]), Shaka instead listens for a PUBLISH_NAMESPACE announcement from the server and uses the advertised namespace automatically. Use the explicit form when you know the namespace ahead of time to reduce start-up latency.

authorizationToken (string, default: '')

An optional authorization token sent to the server during the MoQT client setup handshake. The token is encoded with alias type USE_VALUE (0x03) per the spec.

player.configure({
  manifest: {
    msf: {
      authorizationToken: 'Bearer my-secret-token',
    }
  }
});

subscribeFilterType (MsfFilterType, default: LARGEST_OBJECT)

Controls the filter applied when subscribing to tracks. Corresponds to the MoQT subscribe filter parameter.

player.configure({
  manifest: {
    msf: {
      subscribeFilterType: shaka.config.MsfFilterType.LARGEST_OBJECT,
    }
  }
});

useFetchCatalog (boolean, default: false)

When true, Shaka retrieves the catalog using a FETCH (one-shot retrieval) instead of an ongoing SUBSCRIBE. Use this when the catalog is static and does not update over the lifetime of the session.

player.configure({
  manifest: {
    msf: {
      useFetchCatalog: true,
    }
  }
});

When false (the default), Shaka subscribes to the catalog track and will pick up catalog updates if the server sends them.

version (MsfVersion, default: AUTO)

Controls which MoQT draft version(s) to negotiate with the server.

Draft-14 and draft-16 are both deprecated and will be removed in v6. Selecting either, whether explicitly or because the server chose its subprotocol under AUTO, logs a deprecation warning. Draft-14 predates the subprotocol-based version negotiation introduced in draft-15 and negotiates in band instead, offering a version list in CLIENT_SETUP. Draft-16 is the last draft before draft-17 rewrote the wire format, so keeping it means carrying a second control plane and a second integer encoding in every build. Move to draft-20 or draft-21 before v6.

Draft-16 and draft-18 are different wire protocols rather than revisions of one: draft-17 replaced the variable-length integer encoding, moved the control plane from a single bidirectional stream to a pair of unidirectional ones, gave each request its own bidirectional stream, and reassigned several message type IDs. Shaka keeps a separate implementation of each behind a dialect, selected once during negotiation.

Draft-18, draft-20 and draft-21 are one family. Draft-20 changed a single thing Shaka can observe -- FETCH lost its Fetch Type field and its Start and End Locations, which moved into the LOCATION_FILTER parameter -- and draft-21 changed nothing at all on the wire, only how the specification is organised. So all three share one implementation, and the newer two exist mainly as separate subprotocol strings for relays to select.

player.configure({
  manifest: {
    msf: {
      version: shaka.config.MsfVersion.DRAFT_21,
    }
  }
});

The version is negotiated via the WebTransport subprotocol. Note that Shaka does not require the server to echo the subprotocol back: some relays accept the offered subprotocol while leaving WebTransport.protocol empty, and treating that as a failure would break otherwise working connections.

When the server does not echo and more than one draft was offered, the choice is ambiguous, so Shaka reconnects offering one draft at a time, newest first, until one is accepted. That costs up to one WebTransport handshake per supported draft on such relays. If you know which draft your relay speaks, setting version explicitly avoids it.

catalogPreprocessor (function, default: identity)

An optional callback invoked after the catalog JSON is parsed, before Shaka processes its tracks. Use this to modify or filter catalog entries programmatically.

player.configure({
  manifest: {
    msf: {
      catalogPreprocessor: (catalog) => {
        // Example: remove loc tracks from the catalog
        catalog.tracks = catalog.tracks.filter(
            (t) => t.packaging !== 'loc');
        return catalog;
      },
    }
  }
});

The function receives and must return a msfCatalog.Catalog object.

Full Configuration Example

player.configure({
  manifest: {
    msf: {
      fingerprintUri: '',           // Set for self-signed cert servers
      namespaces: ['live', 'ch1'], // Known namespace; leave [] to auto-discover
      authorizationToken: '',       // Bearer token if required by server
      useFetchCatalog: false,       // true = one-shot FETCH, false = SUBSCRIBE
      version: shaka.config.MsfVersion.AUTO, // Version negotiation strategy
      subscribeFilterType: shaka.config.MsfFilterType.LARGEST_OBJECT,
      catalogPreprocessor: (catalog) => catalog, // Identity (no-op)
    }
  }
});

DRM with MoQ

DRM configuration for MoQ streams works exactly like DASH or HLS. DRM information is carried in the catalog via contentProtections entries (which include the key system UUID, PSSH, and license server URL). Shaka extracts this automatically and populates its DRM subsystem.

You only need to provide additional DRM configuration if the catalog does not include the license server URL, or if you require advanced options such as hardware robustness or custom headers:

player.configure({
  drm: {
    servers: {
      'com.widevine.alpha': 'https://license.example.com/widevine',
      'com.microsoft.playready': 'https://license.example.com/playready',
    },
    advanced: {
      'com.widevine.alpha': {
        videoRobustness: ['HW_SECURE_ALL'],
        audioRobustness: ['SW_SECURE_CRYPTO'],
      }
    }
  },
  manifest: {
    msf: {
      namespaces: ['live', 'encrypted-channel'],
      authorizationToken: 'my-token',
    }
  }
});

await player.load(uri, null, 'application/msf');

Testing with a Local Relay

When running a local MoQT relay with a self-signed TLS certificate, use the fingerprintUri option:

1. Generate a self-signed certificate and export its SHA-256 fingerprint as a hex string (no colons, no spaces) into a plain-text file, e.g. cert.hex.
2. Serve that file from an HTTPS endpoint accessible to the browser.
3. Configure Shaka:

player.configure({
  manifest: {
    msf: {
      fingerprintUri: 'https://localhost:4443/cert.hex',
      namespaces: ['test'],
    }
  }
});

await player.load('https://localhost:4433/moq', null, 'application/msf');