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.
In this article:
Multiple streaming locators per asset
Content protection integration
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.
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.