White paper Viz One APIs. Overview of our API Offering

Transcription

1 White paper Viz One APIs Overview of our API Offering The Viz One is more than just a production, management and distribution system. A broad range of APIs, extend its capacity to numerous alternative media applications. These APIs abstract low level media asset management operations like transcoding and delivery mechanisms, freeing the developer to focus on their design visions. Comprehensive control is offered over procedures like content transcoding, metadata manipulation, storage logic operations, creating playlists, and publishing to and from external systems. The APIs can also integrate video to both web and mobile platforms. The APIs are based on REST and support rapid event based processing. 1

2 Copyright 2014 Vizrt. All rights reserved. No part of this software, documentation or publication may be reproduced, transcribed, stored in a retrieval system, translated into any language, computer language, or transmitted in any form or by any means, electronically, mechanically, magnetically, optically, chemically, photocopied, manually, or otherwise, without prior written permission from Vizrt. Vizrt specifically retains title to all Vizrt software. This software is supplied under a license agreement and may only be installed, used or copied in accordance to that agreement. Disclaimer The information in this document is believed to be correct as of the date of publication. However, our policy is one of continual development so the information in this guide is subject to change without notice, and does not represent a commitment on the part of Vizrt. Technical Support For technical support and the latest news of upgrades, documentation, and related products, visit the Vizrt web site at 2

3 Creating your own media applications Details and Examples Asset Entry API Storing metadata and assets from external systems Retrieving an asset s proxy video URL for preview Aggregate Asset API Representing on air assets Billing API Calculating premium content user charges Consumer API Receiving new media alerts from field reporters Content Management API Controlling the quality of service (QoS) of multi platform video Adding device adapted graphics to multi platform video Device Detection API Serving device adapted video and graphics Folder API Organizing and sharing high value archive material Logging API Storing legacy log sheet information against an asset entry Playlist API Managing a playlist of transmission ready asset entries Program API Managing program production assets within Viz One Publishing API Publishing assets to playout servers Reporter API Building your own Viz Reporter user registration portal Series API Transfer API Triggering automatic file QC using external system Exporting media to a folder User and Group API Restricting access to assets Monitoring Resources Workflow automation and execution Sample Request Command Result Summary Technical Specifications 3

4 Creating your own media applications The Viz One is more than just a production, management and distribution system. A broad range of APIs, extend its capacity to numerous alternative media applications. These APIs abstract low level media asset management operations like transcoding and delivery mechanisms, freeing the developer to focus on their design visions. Comprehensive control is offered over procedures like content transcoding, metadata manipulation, storage logic operations, creating playlists, and publishing to and from external systems. The APIs can also integrate video to both web and mobile platforms. The APIs are based on REST and support rapid event based processing The Viz One architecture is modelled on resources and events. REST APIs are employed extensively for communication across system components. This provides a framework for customers and third parties to create a wealth of new features and integrations. It also ensures a significant API user base from within Vizrt, since in house development of most system components also relies on the APIs. Our aim is that with each new release, as the APIs grow, they remain relevant, efficient, fully documented and reliably stable. The APIs themselves are provided either as HTTP or HTTPS, delivering accessibility across all current software platforms. Vizrt Professional Services teams stand willing to assist with most aspects of API usage, with expertise in design, development or support. Details and Examples Viz One APIs come in several flavours. The rest of this publication describes each API with a few common uses. The table below suggests which type of system can best make use of each specific API. Fig 1. The Viz One APIs Asset Entry API This is the primary digital asset entity around which many Viz One workflows center. Typically it contains one piece of media, together with associated proxy and metadata. The API enables creation, retrieval. updating and deletion of an asset and associated metadata. Media upload and preview tasks are also handled by an Asset Entry API. 4

5 Storing metadata and assets from external systems Asset Entries can be used for storing metadata held in an external system, either as a complete asset entry or alongside the metadata of an existing asset entry. The API can also be used to create asset entries and update their associated metadata. Retrieving an asset s proxy video URL for preview Asset Entries containing video always have proxy video available for use by external systems. The API facilitates retrieval of Viz One proxy video URLs and keyframes that enable remote playback of the proxy version. Proxy video is also accessed this manner from several Vizrt products. Aggregate Asset API An aggregate asset represents a compound of assets entries. The purpose of the aggregate asset is to represent a single piece of content that can be broadcast on air, but requires multiple pieces of media and segmentation for performing that broadcast. In most respects an aggregate asset looks and behaves as an asset entry. The API allows creation, retrieval, updating and deletion of aggregate assets. Representing on air assets A typical aggregate asset could contain a video asset and a subtitle asset. Broadcasting the aggregate asset would mean broadcasting the video with subtitling. In a scenario where subtitles are generated from an external system, the API can be used for either creating an aggregate asset from scratch and then linking to a video and subtitle asset entry, or just updating an existing aggregate asset. Billing API Billing, and ultimately monetization, is an important aspect of any multi platform strategy. This API is designed for integrating a production system s multi platform media usage with a telecommunications company s own billing API. Calculating premium content user charges The API is typically used for charging of premium content usage. Consumer API The consumer is considered as anything that wants to consume multi platform media. Typically this is either a web interface that provides media, or a user account that shall be notified of new media. The API itself provides subscription features to these consumers notifying when new media has been prepared for multi platform delivery. Receiving new media alerts from field reporters A reporter in the field can upload video with Viz Reporter. This video can then be rough cut or editorially reviewed before use in a broadcast or publication to web and mobile devices. The API enables subscription to new media events for example updating video contents in a playlist or sending e mail notifications out to users. Video players on a website can also make use of this API for effortlessly accessing latest videos. Content Management API The Content Management API controls multi platform workflows, like creation, transcoding, publishing, consumption and deletion of content. The purpose of this API is twofold. First, it enables a full feature set API perform these workflows. Secondly, it offers additional features that protect any premium content that requires end user authentication prior to consumption. This second aspect is closely related to the Billing API above. 5

6 Controlling the quality of service (QoS) of multi platform video When video is to be published for multi platform delivery, there are often many parameters requiring control. These include as aspects like what QoS should to be used and where the video is intended to be published. The API allows publishing videos and controlling QoS parameters and other output options. Adding device adapted graphics to multi platform video In addition to video, assets can contain multiple layers of graphics. As with the video and audio content, graphics are also device adapted for delivering an optimal user experience across all viewing devices. The API can be used to superimpose multiple graphics layers to an asset. Device Detection API The Device Detection API can determine the type of video player device the viewer has, to then provide the most appropriate video and graphics quality for that device. Serving device adapted video and graphics Providing device adapted video and graphics, involves an initial transcoding to a wide variety of devices, before integrating these assets into the video player. The API is typically used in conjunction with the Consumer API and Content Management API to enable your web and mobile platforms deliver the best user experience across the many different devices. Folder API The folder represents an ordered collection of entries with metadata. Member entries can be of almost any type including other folders. This allows the creation of folder structures for almost any purpose. Specifically, this API enables creation, retrieval, updating, and deletion of folders. Organizing and sharing high value archive material Folders offer an elegant method for the organizing and sharing of high value material. For example folders can be auto created based on metadata from other systems. The API can be used for placing additional entries in a folder, moving entries up and down in the folder, or for managing the folder s metadata. Logging API Logging is represented by entries called log track items. These log track items correspond to individual annotations or catalogue metadata for an expressed part of media, in point and duration. Log track items themselves, are always part of a log track. A track is the place where multiple log track items of similar types, such as QC, compliance notes or edit notes are grouped. The API allows creation, retrieval, updating and deletion of both log tracks items and log tracks. Storing legacy log sheet information against an asset entry Cataloguing notes held in an XML log sheet from an external logging tool can be stored as log tracks and log track items in Viz One. The API can be used to create a log track and then create component log track items for all the catalogue notes contained in the sheet. Playlist API The Playlist API allows creation, retrieval, updating and deletion of playlists. The playlist is an entry that describes a sequential list of assets, or asset segments, that should be played out sequentially from one or more locations at a scheduled time. 6

7 Managing a playlist of transmission ready asset entries Playlists can be used to store all transmission ready asset entries (or place holders) for a given day and channel. Using the API, entries can be moved up and down in the playlist, with more asset entries being added or removed from the playlist. If a new playlist is needed, the API can be used to create it. Program API The program is intended to contain the various components and broadcast versions that make up a complete broadcast program. This typically includes master video, dubbing, subtitling, and various other aggregate assets required to represent the different transmission copies from a traffic system. The program itself is an ordered collection member entities. Programs are also closely related to Series. The API allows creation, retrieval, updating and deletion of programs. Managing program production assets within Viz One The program can store a hierarchy of diverse media and metadata that is managed through the versioning, dubbing and subtitling of a program. Using this API, external systems, such as planning systems or workflow engines, can create programs and add member entries. Publishing API The Publishing API enables publishing of assets to various types of endpoints, based on a time schedule called the distribution plan. Each distribution plan represents the actual task of publishing an asset to a particular point for a particular timespan. An endpoint is typically a video server, content delivery network or network folder. The API allows creation, retrieval, updating and deletion of distribution plans. Publishing assets to playout servers The distribution plan can be used for controlling when media shall be published to a playout server. The plan will control how long media should remain on the playout server. Using the API one can easily create distribution plans to ensure media is published to correct endpoints at correct times. Reporter API The Reporter API manages users of the Viz Reporter app. Only registered users can upload reports from their phones. Building your own Viz Reporter user registration portal The API can be used for constructing your own Viz Reporter user s registration portal. Additionally, it can expose registration, allowing re use of the app on a website as a widget or similar. Series API The series represents an ordered collection of member entities. The Series uses explicit mark up to state what types of member entities are supported and provides facilities for adding first and last members. The Series members also provide a way of adding members before an existing member. Members can be reordered using the operations move first, move last and move before existing member type, through links in the Series and Series Members. Series are closely related to Programs. Transfer API The transfer typically represents a file transfer job of moving a file to a certain file storage, for example a playout server, but can also represent a background transfer job such as rendering an edit decision list and creating a new asset. The API allows creation, retrieval, updating and deletion of transfers. 7

8 Triggering automatic file QC using external system In a system that supports an external QC system such as Interra Baton QC, the API can be used for triggering a background transfer job, so that Baton performs a file quality check of an asset. Exporting media to a folder A transfer can export media to a folder for a user or third party system to pick up. The API also enables the triggering of various transfer methods, including the export of media to a folder. User and Group API Users and Groups are a common concept used by most systems. In addition to these concepts, the Viz One also has Access Control Lists (ACL) for controlling which groups and users have access to a certain resource and whether they can read it and/or update it. This API allows creation, retrieval, updating and deletion of both users and ACLs. For groups, the API only offers retrieval as these are typically managed through the Viz One's Administration Console or an external Active Directory server. Restricting access to assets In the majority of larger systems, fine grained access control is required. Often the level of access to an asset will change during its life time. Flexible manipulation of access control lists is achieved through the combination of this API and the respective API of the entry type being modified. This allows an external system such as a workflow engine to update the ACL of an asset once a particular task against the asset, for example approval, has been completed. Monitoring Resources Many system integrations require some form of entry monitoring to maintain an update relationship. Most of the APIs of Viz One allow provision of a monitor URL, where a client can subscribe to notifications of changes to an entry. This enables applications to listen for particular events against entries in the system, rather than polling for them. Operating on events is highly preferable, since it allows rapid asynchronous processing. This effectively eliminates the overhead of inefficient polling that often causes two systems to be out of synch for several seconds or minutes. Workflow automation and execution When a workflow engine shall control various types of tasks in the system, notifications are often a key tool. This allows the workflow engine to perform operations based on received notifications, rather than busily poll an API for system changes. The result is fine grained and instant control over metadata updates and other tasks, directly in the workflow engine. This allows for enhanced task management and workflow implementation. Sample Request The following code shows a sample request using the freeware tool curl, which is available for Windows, Mac and Linux. In this example, the Asset Entry API retrieves all assets of type item with a single result per paginated return. When running this example, remember to replace username, passwords and hostname with the actual values for the system to which you are sending the request. Command $ curl insecure user "$VMEUSER:$VMEPASS" include header "Accept: appliction/atom+xml;type=feed" " Result 8

9 HTTP/ OK Date: Wed, 14 Mar :24:55 GMT Server: Apache/ (Linux/SUSE) Set Cookie: token=hhbnuopgaruk Iq _bsbx9vensceeexk D0Dtsj0k4wSDTfgAqPRqp40I1OTrVUs4H1MlWn2ZWAo79BKujr9w..; Path=/; Expires=Thu, 15 Mar :24:55 GMT; Secure Transfer Encoding: chunked Content Type: application/atom+xml;type=feed;apitype=asset3dp.itemcollection; charset=utf 8 <?xml version="1.0" encoding="utf 8"?> <atom:feed xmlns:opensearch=" /spec/opensearch/1.1/" xmlns:vizmedia=" xmlns:core=" xmlns:media=" xmlns:atom=" xmlns:mam=" type="application/atom+xml;type=feed;apitype=asset3dp.itemcollection" <atom:id> <atom:link rel="self" href=" <atom:link rel="search" type="application/opensearchdescription+xml" href=" <atom:title>text search query 'item.search.creationdate:[* TO *]'</atom:title> <atom:link rel="next" href=" <opensearch:totalresults>4</opensearch:totalresults> <opensearch:startindex>1</opensearch:startindex> <opensearch:itemsperpage>1</opensearch:itemsperpage> <atom:entry type="application/atom+xml;type=entry;apitype=asset3dp.item"> <atom:title>metadata breakthrough</atom:title> <core:ardomeidentity name="id"> </core:ardomeidentity> <atom:link rel="invoker" type="application/vnd.vizrt.easycut+xml" href=" <atom:link rel="invoker" type="application/vnd.vizrt.precut+xml" href=" <atom:link rel="invoker" type="application/vnd.vizrt.shotcut+xml" href=" <atom:link rel="invoker" type="application/vnd.vizrt.medialogger+xml" href=" <atom:updated> T17:03:33.000Z</atom:updated> <atom:category scheme=" term="asset"/> <atom:category scheme=" term="news"/> <atom:category scheme=" term=""/> <atom:category scheme=" term=""/> <atom:content type="application/mxf" src=" <media:group> <media:content type="video/mp4" url=" bitrate=" " framerate="25" samplingrate="48" channels="2" width="640" height="360" duration="1"/> <media:content type="application/mxf" url=" bitrate=" " framerate="25" samplingrate="48" channels="4" width="1920" height="1080" duration="1" isdefault="1"/> <media:content type="audio/mpeg" url=" bitrate="112000" samplingrate="48" channels="1" duration="1"/> <media:content type="audio/mpeg" url=" bitrate="112000" samplingrate="48" channels="1"/> <media:content type="audio/mpeg" url=" bitrate="112000" samplingrate="48" channels="1"/> <media:content type="audio/mpeg" url=" bitrate="112000" samplingrate="48" channels="1"/> <media:content type="video/mp2t" url=" bitrate=" " framerate="25" samplingrate="48" channels="2" width="640" height="360" duration="1"/> <media:content type="application/vnd.vizrt.ardok" url=" width="192" height="108"/> </media:group> 9

10 <media:thumbnail url=" <vizmedia:media>video</vizmedia:media> <mam:derivativefilename>dizyhgallyifiixj</mam:derivativefilename> </atom:entry> </atom:feed> Summary The Viz One APIs abstract low level media asset management, transcoding and delivery mechanisms, freeing developers to focus on their design tasks. They also provide a reliable long term interface on which integrations can be built. Vizrt Professional Services teams can assist with most aspects of API usage, whether you require help with design, development or support. API Technical Specifications Protocols Security Compatibility Based on REST with support for rapid event based processing. Secure HTTPS authentication where applicable with access right, Active Directory and LDAP integration Applications in Cocoa, C/C++, C#, Java, JavaScript, Objective C, Perl, PHP, Python, and Ruby can all use the APIs 10