App Cloud
- Overview and general topics
- Product Updates
- Glossary
- The App Cloud SDK
- Creating an app template
- Tutorials
- Content optimization
- Development tips and best practices
- Packaging a template
- Creating apps from a template
- Publishing an app
- Delivering ads
- Push Notifications
- Analytics
- Managing users and accounts
Player Debugger
Resources
Accessing Video Content with the Media API
This document shows how to access video metadata, including the video file itself, using the read methods of the Media API.
Important Notes on Use of the Media API
Heed these important notes before using the Media API.
Do not hard-code video and image URLs
URLs for thumbnails, stills, video files, and other media should never be hard-coded in your pages or applications. The Media API will always return the current current URLs for media files, but the URLs themselves are subject to change. You should use Media API calls to retrieve these URLs each time the page loads, or cache them for no more than six hours.
Caching video and image URLs
You can cache URLs for videos and images to improve page performance, but the cache must be refreshed regularly. If you cache the URLs you retrieve to improve the performance of your pages, be sure to refresh the cache by repeating the API calls at least once every six hours.
See Best Practices for Embedding Video Cloud Media for more information.
Retrieving video properties
When you use a read method in the Media API to get a video, you specify which properties of the video you want to be returned with the video_fields parameter in the method call. For example, to get a video's name and duration, you might use a find_video_by_id call, as follows:
http://api.brightcove.com/services/library?command=find_video_by_id&video_id=1520880903001&video_fields=name,length&token=jskS1rEtQHy9exQKoc14IcMq8v5x2gCP6yaB7d0hraRtO__6HUuxMg..
Getting the URL for a progressive download video
For progressive download video, the FLVURL property of a Video object represents the URL of the video. If you want to get the URL of the video itself and not just its metadata, add FLVURL to the fields parameter, as follows:
http://api.brightcove.com/services/library?command=find_video_by_id&video_id=1520880903001&video_fields=name,length,FLVURL&token=jskS1rEtQHy9exQKoc14IcMq8v5x2gCP6yaB7d0hraRtO__6HUuxMg..
See the results of this call in a new window or tab.
Note that the FLVURL property of a Video object represents the video's URL, no matter whether the video's encoding is FLV (VP6) or H.264.
Getting the video URL for streaming video
You can use the Media API to deliver video assets by progressive download from a Video Cloud account that's set up for streaming content. By setting up your streaming account for Universal Delivery Service (UDS), you can enable delivery by progressive download in response to Media API calls. Note that UDS does not work with remote assets. To indicate that a video should be delivered by progressive download from a streaming/UDS account, use the Media API read methods with the optional media_delivery=http argument.
http://api.brightcove.com/services/library?command=find_video_by_id&video_id=1520880903001&video_fields=name,length,FLVURL&media_delivery=http&token=jskS1rEtQHy9exQKoc14IcMq8v5x2gCP6yaB7d0hraRtO__6HUuxMg..
See the results of this call in a new window or tab.
For more information, see Setting Video Delivery Options.
Accessing Apple HLS renditions
You can use the Media API to deliver Apple HTTP Live Streaming (HLS) renditions of your videos to iOS devices. To indicate that an Apple HLS rendition of a video should be delivered, use the Media API read methods with the optional media_delivery=http_ios argument.
http://api.brightcove.com/services/library?command=find_video_by_id&video_id=1520880903001&video_fields=name,length,videoFullLength&media_delivery=http_ios&token=jskS1rEtQHy9exQKoc14IcMq8v5x2gCP6yaB7d0hraRtO__6HUuxMg..
See the results of this call in a new window or tab.
This returns the HTTP URL of the master index file as the videoFullLength parameter. For more information about creating and delivering Apple HLS video renditions, see Delivering Videos with Apple HTTP Live Streaming.
Accessing multi-bitrate streaming renditions
If this video includes multiple renditions for multi-bitrate streaming, the URL returned is for the default rendition. If you want to get all of the renditions, the MP4 renditions and the M2TS renditions (for iOS devices) are returned in separate arrays of objects. To return the MP4 renditions, you need to include renditions in the video_fields argument, and iosrenditions to return the M2TS renditions.
Note that when you request iosrenditions, the only output option is JSON.
http://api.brightcove.com/services/library?command=find_video_by_id&video_id=1520880903001&video_fields=name,renditions&token=jskS1rEtQHy9exQKoc14IcMq8v5x2gCP6yaB7d0hraRtO__6HUuxMg..
See the results of this call in a new window or tab.
The renditions property is included by default in the fields returned. If multiple renditions exist and if you have the proper URL token, the renditions will be returned unless you specify the fields you want and do not include renditions in the fields. Note that you can access the URL only if you have enabled delivery of videos by progressive download, not just streaming, as described in the topic, Setting Video Delivery Options. The Media API Object Reference lists the properties returned in the Rendition object.
Security for video URLs
You need to be even more careful about guarding access to the URLs for your video assets than you do for your video metadata. To provide better security, the Media API requires a special token to allow access to the FLVURL property of videos. Your regular Media API read or write token will not work for this purpose. In the topic Managing Media API Tokens, learn how to get a special Media API token for read or write access to the FLVURL property.
