RMS Concepts - Streaming Locators – Ravnur

Overview

Streaming locators are essential components in Ravnur Media Services that enable content delivery to end users. A streaming locator creates the connection between your encoded media assets and the streaming endpoints that deliver content to viewers, defining how and when content can be accessed.

What Are Streaming Locators?

A streaming locator is an object that generates streaming URLs for your media content. It acts as the bridge between your stored assets and your audience by:

Linking Key Components:

The encoded asset (your media content)
A streaming policy (defines protocols and encryption)
A streaming endpoint (the delivery infrastructure)
Optional content keys (for encrypted content)

Generating Access URLs: Streaming locators produce the actual URLs that client applications and players use to stream your content.

Controlling Access: They define when content is available through start and end times, and can work with content protection systems to restrict access.

Publishing Content

To make videos in the output asset available to clients for playback, you must create a streaming locator and then build streaming URLs. The process of creating a streaming locator is called publishing.

By default, the streaming locator is valid immediately after you make the API calls and lasts until it is deleted, unless you configure the optional start and end times.

How Streaming Locators Work

When you create a streaming locator, you must specify:

Asset Name (required) - Which media asset should be made available for streaming

Streaming Policy Name (required) - Which delivery format and protection scheme to use (clear streaming, AES encryption, DRM, etc.)

Start Time (optional) - When the content becomes available. Defaults to immediately if not specified.

End Time (optional) - When the content should no longer be accessible. Defaults to 100 years if not specified.

Locator ID (optional) - A custom identifier for the locator. If not provided, a GUID is automatically generated.

Filters (optional) - Dynamic manifest filters to create sub-clips or alternative renditions without re-encoding.

You can specify the start and end time on your streaming locator, which will only let your users play the content between these times (for example, between 5/1/2022 to 5/5/2022).

Once created, the streaming locator generates streaming URLs in various formats (HLS, DASH, Smooth Streaming) that can be provided to media players.

URL Generation

To build a streaming URL, you need to concatenate the streaming endpoint hostname and the streaming locator path. After creating a streaming locator, you can build streaming URLs using this pattern:

https://{streaming-endpoint-hostname}/{locator-id}/{asset-filename}.ism/manifest(format={format})

Supported formats include:

HLS - format=m3u8-cmaf
DASH - format=mpd-time-cmaf

Multiple Streaming Locators per Asset

A single asset can have multiple streaming locators, each serving different purposes. This flexible architecture enables various content delivery scenarios.

Common Use Cases

Tiered Content Access:

Locator 1 - Clear streaming for free preview or trailer (using Predefined_ClearStreamingOnly)
Locator 2 - DRM-protected streaming for premium subscribers (using Predefined_MultiDrmStreaming)
Locator 3 - Download option for offline viewing (using Predefined_DownloadAndClearStreaming)

Time-Based Availability:

Locator 1 - Available for 48-hour rental period with specific start/end times
Locator 2 - Permanent access for users who purchased the content (no end time)

Regional Distribution:

Locator 1 - For North American distribution with specific DRM requirements
Locator 2 - For European distribution with different compliance needs
Locator 3 - For Asian markets with region-specific streaming policies

Testing and Production:

Locator 1 - Internal testing with clear streaming and no restrictions
Locator 2 - Production deployment with full encryption and token authentication

Device-Specific Delivery:

Locator 1 - FairPlay DRM for iOS/tvOS devices
Locator 2 - Widevine DRM for Android devices
Locator 3 - PlayReady DRM for Windows/Xbox devices

Content Protection Integration

Streaming locators work seamlessly with content protection systems:

Clear Streaming - No encryption, content is freely accessible to anyone with the URL

AES-128 Envelope Encryption - Content keys delivered through Azure/Ravnur key delivery service

DRM Protection - Integration with PlayReady, Widevine, and FairPlay DRM systems

Token Authentication - JWT or SWT tokens can be required to access content keys, preventing unauthorized access

When using encryption, the streaming locator coordinates with the key delivery service to ensure only authorized clients receive the decryption keys.

For more information, see Content Key Policies.

Dynamic Manifest Filters

Streaming locators can reference filters that modify the streaming manifest without re-encoding the asset:

Time Trimming - Create clips or remove sections (e.g., ads, credits)

Bitrate Filtering - Limit available quality levels for different subscription tiers

Track Selection - Offer different audio languages or subtitle options

DVR Window - For live content, define how much time-shifted viewing is available

Filters can be applied at the account level, asset level, or per streaming locator, providing granular control over what viewers can access.

Important Considerations

Streaming Locators Are Not Updatable - Once created, streaming locator properties cannot be modified. If you need different settings, you must create a new streaming locator.

DateTime Properties Use UTC Format - All properties of streaming locators that are of the DateTime type are always in UTC format.

Design a Limited Set of Policies - You should design a limited set of streaming policies for your RMS account and reuse them for your streaming locators whenever the same options are needed. This simplifies management and ensures consistency.

Asset Dependency - The underlying asset must exist for the locator to function; deleting an asset breaks all its locators.

Immutability - The streaming policy associated with a locator cannot be changed after creation; you must create a new locator with a different policy.

Best Practices

Use Descriptive Locator IDs - When specifying custom locator IDs, use meaningful names that indicate the purpose (e.g., premium-subscribers-2024 or free-trial-access)

Set Appropriate Expiration Times - Always define end times for temporary content to prevent indefinite access and potential security issues

Leverage Multiple Locators - Don't re-encode assets for different access scenarios; create multiple locators with different policies instead

Reuse Streaming Policies - Maintain a limited set of well-defined streaming policies and reuse them across locators to simplify management

Monitor Locator Usage - Track which locators are actively being used to optimize your content delivery strategy

Clean Up Expired Locators - Regularly remove streaming locators that are no longer needed to maintain a clean environment

Test Before Production - Create a test locator first to verify URLs and playback before providing access to end users

Lifecycle Management

Streaming locators remain active until their expiration time or until explicitly deleted. Key considerations:

Deletion - Deleting a streaming locator immediately invalidates all associated URLs, stopping content access

Default Validity - By default, streaming locators are valid immediately after creation and last until deleted (or 100 years if no end time is specified)

Publishing Process - The act of creating a streaming locator is called publishing, making your content available for playback

Search

Ravnur Knowledge Base

RMS Concepts - Streaming Locators