About: Using HTTP Live Streaming (HLS) from Alta Aware

Last modified: Tuesday May 21, 2024.

HTTP Live Streaming (HLS) is a commonly-used method for streaming live video, recorded vidoe, or bookmarked Saved clips to an to web page, webapp, or other viewer that uses a suitable HLS Javascript library. You can also view HLS streams on media players such as VLC, ffmpeg/ffplay, or GStreamer.

The HLS protocol is built on top of HTTP. The client sends HTTP requests to download playlists and media chunks from Alta Aware. Each chunk contains abut one second of video and audio from the stream. This means that the HLS client sends two requests per second, one to download the updated media playlist, and the other to request the next media chunk. The Aware HLS service buffers six seconds of media before responding to the initial client request. This leads to a short delay in serving the video when the stream is first loaded.

This provides a method for you to take the live, recorded, or bookmarked video streams from your Alta Aware deployment, and then view it in a monitoring system or on a web application, for example to show customers that there are live feeds from your video security system.

The HLS service takes care of requesting the streams using the Aware Cloud API's and handles the media path negotiations to the source of the video stream.

Table 1 – Key to Figure 1

Item	Description
	The client application makes an HLS request using the URL to the Alta Aware HLS  service.
	The HLS service uses the credentials from that HLS request to authenticate with the Aware Cloud deployment.
	After successfully authenticating, the HLS service performs the API requests to the Aware Cloud deployment to set up the required stream. This includes information about the camera to stream, whether it is a live stream, playback of recorded video, or a bookmarked saved clip, the time to start the playback, as well as other parameters.
	The stream negotiation takes place, with the client end being the HLS service. Media may flow directly from the device to the HLS service, or via a TURN server.
	Media flows from the requested device to the HLS service. The HLS service then sends the video data to the client application using HTTPS.

Use the Aware Cloud API to collect the information needed to form the URL needed to request and stream the video from an Aware Cloud deployment to your application.

URL structure

For viewing live video and playback, the URL is in the format: https://<deploymentname>.stream.<region>.alta.avigilon.com/<streamMode>?deviceId=<deviceId>&<parameters>

For bookmarked Saved clips, the URL is in the format:

 Where:

• Only HTTPS streams, are allowed.
• <deployment> is the first part of the name of your Alta Aware deployment. This is the information at the beginning of the URL you use at access your Aware Cloud deployment, or that you use to log into the Alta Aware mobile app.
• <region> to keep the shortest routing of the video, use the region to which your deployment is associated. For example, us1 or eu1.
• <streamMode> is streams for viewing live video and playback to view historic video.
• <deviceId> is the GUID for the camera to stream.
• <BookmarkToken> is the token that identifies the bookmark of interest.
• <parameters> are the additional information needed for your chosen stream. For example:
  • When streaming live video, you can optionally specify the height and width for the stream, for example, &height=360&width=720
  • When playing back historic video, specify the time that the video should start, for example, &startTimestamp=2024-05-15T07:20:00.00Z
    

    Timestamps should be entered using the UTC/GMT timezone.

  • For bookmarks, you can specify the source from a multi-source device by using the pane=<n> parameter, where n is the number of the required source. This defaults to source 1 if not defined.

    Currently, you cannot use HLS to view password-protected Saved clips.

• Authentication of the application user is done via the credentials supplied with the HLS request. The same credentials can be used for the HLS and other API requests.

  You can take the URL you use to connect to your Aware deployment, and edit it by adding .stream between the deployment name and the region. You then need to add the <streamMode>, <deviceId>, and <parameters> for your chosen HLS stream.

You cannot use the username and password embedded within into the HLS URL when streaming to a website or webApp, as the command ignores credentials. You can embed username and password credentials into the URL if you are streaming to a non-web video player such as VLC.

Depending on the application receiving the stream, you might be able to embed the credentials for non-web video players. Edit the string to include <username>:<password>@ immediately before the deployment information, as follows: https://<username:password>@<deploymentname>.stream.<region>.alta.avigilon.com/hls/<streamMode>?deviceId=<deviceId>&<parameters>

Use the credentials for a configured Alta Aware user that has the relevant permissions for the selected device.

When streaming to external websites or webapps, you need to whitelist the site using cross-origin resource sharing so that Alta Aware can successfully stream to the site. See How to: Configure cross-origin resource sharing in Alta Aware

Required permissions

The authentication for HLS streams is sent in plain text. Because of this, we recommend you create a user account that has only the permissions required for the type of streaming you are planning. When using the HLS service, ensure that the Aware user account used with the HLS service has the relevant permissions:

• For streaming of live video — the Aware Cloud user account must include the View live video general permission for the relevant device.
• For playback of historic video — the Aware Cloud user account must include the View historic video general permission for the relevant device.

All other permissions should be disabled, to prevent the user credentials being used to gain unauthorized access to your Alta Aware deployment.

Also, ensure that the user account is added to a suitable User Group.