This sample demonstrates how to use the Shaka player with HLS low latency live streaming (LL-HLS) and timed metadata insertion. Azure Media Services supports playback in any Javascript Media Source Extension based player that can support the streaming of HLS, Low latency HLS (LL-HLS) and MPEG DASH formats. The Google Shaka player is a good choice for an open source player solution that works well with AMS streaming.
Timed metadata is custom data that is inserted into a live stream. Both the data and its insertion timestamp are preserved in the media stream itself so that all the clients playing back the video stream can get the same custom metadata at the exact same time in relation to the video stream.
In addition, the Shaka player supports timed metadata through the use of the Event Message payload format as defined in the Alliance for Open Media Carriage of ID3 Timed Metadata in the Common Media Application Format specification. This industry standard allows the use of ID3 timed metadata messages to be signaled in the HLS or DASH streaming format and signal a player to fire an event when received.
Media Services always wraps the message into an ID3 'GEOB' - generic object which has the following layout:
Format:
// Text encoding $0x0 (00) | UTF8 = $0x03
// MIME type 'application/json' $0x0 (00)
// Filename <text string - which will be empty from AMS> $0x0 (00)
// Content description <text string - which will be empty from AMS> $0x0 (00)
// Encapsulated object <binary data> Both the Apple HTTP Live Streaming (HLS) specification and the MPEG DASH streaming specifications support the inclusion of timed metadata in ID3 format using event message payloads.
- Node.js
- VS Code
- Shaka Player 4.2.3 or higher
- Vite - if you want to launch the sample locally
The sample can be launched using the Vite server simply by running the following command:
npm run devSteps:
- Run npm install to install the package.json requirements for Shaka player
- The sample can be deployed to any web server, or simply launched from VS Code using the Vite server module
- npm run dev
- Optionally run the sample on StackBlitz with the button below
Click the following button to launch a fork of this code on StackBlitz.com
Once you are running in StackBlitz, you can hit F12 to open the Developer Tools window and monitor the console.
Timed metadata is sent to a live event via a POST to the endpoint for timed metadata. This endpoint is specified in the TimedMetadataEndpoints property of the LiveEvent. Any tool can be used to send the http post including Postman, Curl, VS Code extensions for REST or HTTP requests, and any SDK that can send an HTTP post to the endpoint.
The format of the timed metadata endpoint is also deterministic based on the RTMP ingest URL for the live event. The metadata endpoint uses the following format:
https:// <> .channel.media.azure.net/<<LIVE_INGEST_ID>>/ingest.isml/eventdata
When using Curl, you must set the header using -H “Content-Type: application/json” Use the -d flag to set the JSON data on the command line (escape quotes in the JSON body with a backslash when using the command line). Optionally you can point to a JSON file using -d @.
A POST is implicit when sending data in, so you do not need to use the -X POST flag.
curl https://<<LIVEEVENTNAME>>.channel.media.azure.net/<<LIVE_INGEST_ID>>/ingest.isml/eventdata -H "Content-Type: application/json" -d "{\"message\":\"Hello from Seattle\"}" -v
Total message body payload size: 256 kb max payload for the JSON body. Any requests exceeding limit will get a 429 TOO MANY REQUESTS response code for back from the server. If it is larger than 256kb, then service returns 400.
Requests per second: Max 2 requests per second. Server will return a throttling error response if exceeded.