Simple Content Browsing Protocol
Specification Version 0.5
SCBP is a protocol specification for content browsing and searching.
Like all SIMS protocols, this standard defines a set of resources or “actions” in the form of an HTTP GET (or POST) request which returns a response in XML or JSON format. The HTTP method does not strictly conform to REST conventions, as GET may represent retrieval, creation, modification or deletion of data on the server. POST is required only when the client is posting a large amount of data to the server, such as a bulk load of content metadata. All actions are assumed to use HTTP GET unless marked otherwise.
The location of the RADL of a SIMS protocol is discovered via the SCDL service description page. Therefore the only URL which a device must know before-hand is the location of the SCDL service description page, and this may be posted on an informational page on the service’s web site. The recommended URL for such a page is http://hostname/sims. This makes it easy for anyone to figure out how to connect to your service.
Note: Each RADL of a SIMS protocol may define an action url with implicit SIMS parameter values, meaning some SIMS parameter values are not included as a query param, but they are assumed in the url path. Such resources defined in a RADL of a SIMS protocol implementation: a) must include a “sims:action” element within the action element where applicable, and the element value is the name of the SIMS action, b) must include a “sims:implicit” element within the action element where applicable, and its value is the set of implied query params and their values in the format “param1=value1¶m2=value2,…” and c) must always use SIMS parameter names where applicable.
Example SIMS action URL with implicit parameter values:
http://hostname/browse/shows/234/seasons
This example URL is for an SCBP “search” action, and it returns a list of volumes for the show with an id value of 234. In this example, “234″ is an explicit value for the show id parameter. In this case the id value is passed as part of the url path, instead of a query parameter. The “/seasons” section of the url path represents an implicit parameter value: “type=seasonal_series”. This implicit parameter value could be discovered in a RADL for the service’s SCBP API.
Each response must include scbp as the primary element with a version attribute (or child member in the case of JSON) indicating the specification version in the format #.#. See the SCBP XML Schema for a complete specification of the SCBP response objects.
1) Action: capabilities
Parameters (* is optional):
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device* (string)
The device id of the device performing the action.
session* (string)
The session id of the account authenticated session.
Example capabilities Action:
action url: http://hostname/scbp/capabilities
Example XML Response:
<scbp version="x.x" xmlns="http://simsapi.org">
<response>
<code>1</code>
<message>Success.</message>
</response>
<capabilities>
<max_match>500</max_match> [F]
<scopes> [G]
<scope>
<item_type>categories</item_type>
<match>id,name</match>
<result></result>
<sort></sort>
</scope>
<scope>
<item_type>channels</item_type>
<match>id,name,description</match>
<result></result>
<sort></sort>
</scope>
<scope>
<item_type>shows</item_type>
<match>id,name,description,channel.id,category.id</match>
<result></result>
<sort></sort>
</scope>
<scope>
<item_type>volumes</item_type> [H]
<match>id,name,description,number,show.id</match> [I]
<result></result> [J]
<sort></sort> [J]
</scope>
<scope>
<item_type>podcasts</item_type>
<match>id,name,description,channel.id,category.id</match> [K]
<result></result>
<sort></sort>
</scope>
<scope>
<item_type>episodes</item_type>
<match>id,name,description,number,volume.id</match> [K]
<result></result>
<sort></sort>
</scope>
</scopes>
</capabilities>
</scbp>
[F] Maximum number of results allowed by the service. If the requested limit is higher, then this value will be used as the limit. Must be integer without commas.
[G] The service must list all scopes which it supports. Within each scope definition, the service must list all supported match fields and result fields, including any optional and service-specific fields.
[H] The item Type must match one of the SCBP defined item types. A service is not required to support all item types defined by SCBP.
[I] The match element contains a comma separated list of all fields which the service supports for each scope. This includes any match fields defined by SCBP as well as any service-specific match fields. A client should ignore any spaces in this value.
[J.1] The result element contains a comma separated list of fields (not including match fields) which can be included in the result. Any match fields may be included in the result, so only the additional supported result fields beyond the match fields should be listed here. For example, a service may list “name,number” as the supported match fields for a particular scope, and “description” as the only result field. In this example, a search request could include name, number and description as result fields. The id field must be included with each item in the search result, so it is not necessary to include it in the result element within the scope definition. A service may also choose to include additional service-specific result fields. A client should ignore any spaces in this value.
[J.2] The sort element contains a comma-separated list of fields (not including match or result fields) which can be used to sort the result. Any match fields and any result fields may be used for the sort, so only the additional supported sort fields beyond the match and result fields should be listed here.
[K.1] Podcasts may have a channel association, just like shows.
[K.2] Episodes may have an association with a show or a podcast, but not both.
Possible Response Codes:
-1 (unknown error)
-12 (extended error information available)
-24 (missing element)
2) Action: formats
Parameters:
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device* (string)
The device id of the device performing the action.
session* (string)
The session id of the account authenticated session.
id* (string)
The id of the item within the content scope.
scope* (string)
The content scope.
Example formats Action:
action url: http://hostname/scbp/formats
Example XML Response:
<scbp version=x.x>
<response>
<code>1</code>
<message>Success.</message>
</response>
<formats>
<video_format> [J]
<name>video_sd1</name> [K]
<usage>content</usage> [L]
<container>mp4</container> [M]
<bit_rate>600</bit_rate> [N]
<video_track> [O]
<codec>h264</codec> [P]
<codec_profile>4.1</codec_profile> [Q]
<codec_level></codec_level> [R]
<resolution>640x480</resolution> [S]
</video_track>
<audio_track> [T]
<codec>aac</codec> [U]
<codec_profile>lc</codec_profile> [V]
<bit_rate>128</bit_rate> [W]
<sample_size>16</sample_size> [X]
<sample_rate>48</sample_rate> [Y]
<audio_channels>fl,fr,fc,sl,sr,bl,br,lf</audio_channels> [Z]
</audio_track>
</video_format>
<image_format>
<name>image_big_icon</name>
<usage>icon</usage> [L]
<codec>png</codec> [P]
<resolution>100x100</resolution>
</image_format>
</formats>
</scbp>
[J] The format element may have zero or more video_format, audio_format or image_format child elements.
[K] The format name is defined by the service and is case-insensitive.
[L] The intended usage of the format. The following usages are defined for each format type:
video: content, preview, ad
audio: content, preview, ad
image: icon, banner, background, ad
[M] The following containers are defined per media type:
video: mp4, mlv, odf, avi, mkv, flv, mts, asf, m3u-ts, bdmv-ts
audio: mp3, mp4, mla, odf, wav, ogg, mts, asf, flac, m3u
Retrieving media in an m3u container: In the case of content which uses the m3u audio format container, the content url must point to an M3U playlist file which is assumed to contain a list of mp3 audio streams. In the case of content which uses the m3u-ts video format container, the content url must point to a live streaming m3u8 file in the format defined by the IETF Internet Draft draft-pantos-http-live-streaming-02. In the case of content which uses the bdmv-ts video format container, the content URL is a live streaming m3u8 file, and an additional <vfs> element must be present within the <stream> element, and it must point to the url to obtain the jar file for the VFS image.
[N] The bit rate is expressed as an integer without commas. It must be provided in kilobits (Kb) per second.
[O] For media type ‘video,’ there must be one or more video_tracks elements. For media type ‘audio’ there must not be any video_tracks elements.
[P.1] The following codecs are defined for a video_track:
mpeg1, mpeg2, mpeg4, h264, wmv, vc1, real, vp6, theora, sorenson
[P.2] An image format does not use the container element as it is implied in the codec. In the case of a media type ‘image’, the codecs defined are:
png, jpg, gif, bmp
[Q] If no codec profile is defined for a video codec, the codec_profile element must be absent. The following codec profiles are defined per video codec:
mpeg1: (none)
mpeg2: sp, mp, snr, spatial, hp
mpeg4: sp, asp
h264: cbp, bp, mp, xp, hp, sbp, shp, ship
wmv: ap
vc1: simple, main, advanced
real: (none)
vp6: (none)
theora: (none)
sorenson: (none)
[R] If no codec level is defined for a video codec, the codec_level element must be absent. The following codec levels are defined per video codec:
mpeg1: (none)
mpeg2: ll, ml, h14, hl
mpeg4: (none)
h264: 1, 1b, 1.1, 1.2, 1.3, 2, 2.1, 2.2, 3, 3.1, 3,2, 4, 4.1, 4.2, 5, 5.1
wmv: 7, 8, 9
vc1: (none)
real: (none)
vp6: (none)
theora: (none)
sorenson: (none)
[S] Resolution must be in the format of two integers joined by a case-insensitive ‘x’. The first integer represents the horizontal resolution, and the second integer represents the vertical.
[T] For media type ‘video’ there must not be any audio_tracks. For media type ‘audio’ there must be one or more audio_tracks.
[U] The following codecs are defined for an audio_track:
lpcm, mp3, aac, heaac, ac3, eac3, truhd, dts, dtses, dtshd, wma, wmapro, ogg, flac
[V] If no codec profile is defined for an audio codec, the codec_profile element must be absent. The following codec profiles are defined per audio codec:
lpcm: (none)
mp3: (none)
aac: lc, mp, srs, ltp
heaac: v1, v2
ac3: (none)
eac3: (none)
truhd: (none)
dts: (none)
dtses: (none)
dtshd: (none)
wma: 1, 2, 9, 9.1, 9p, 10p, 9l, 9v
vorbis: (none)
flac: (none)
[W] This value represents the bit rate of the audio track only. The bit rate is expressed as an integer without commas. It must be provided in kilobits (Kb) per second.
[X] This value represents the number of bits per sample. It is expressed as an integer without commas.
[Y] This value represents the sample rate in kiloHertz (kHz). It is expressed as an integer or single decimal number.
[Z] The comma separated list of audio channels included in the audio track. It is case-insensitive. The values defined are:
fl, fr, fc, sl, sr, bl, br, lf
Possible Response Codes:
-1 (unknown error)
-12 (extended error information available)
-24 (missing element)
3) Action: search
Parameters: (* is optional)
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device* (string)
The device id of the device performing the action.
session* (string)
The session id of the account authenticated session.
scope (string)
The scope of the search must be one the following item types defined by SCBP:
channels, shows, volumes, episodes, movies, music_videos, artists, albums, songs, audio_books, livefeeds, playlists, items, programs, categories, bookmarks, favorites
match (string)
Uses the form “fieldname:{matching value}+objectname.propertyname<{matching value}|…” where “+” represents AND, and “|” represents OR. A service must support any combination of “+” and “|” in the match string. Where there is a mix of “+” and “|” in the match string, the service should evaluate all OR operators first. You can match multiple fields and you can reuse fields to allow for matching one field against multiple values. If the matching value contains “+” or “|” then the entire matching value must be enclosed within “{}”. The matching value may contain any characters including “{” and “}”; however, a server receiving a match string starting with “{” and ending with “}” should not consider the starting “{” and ending “}” as part of the match string. In the case of fields which are strings, a matching value containing “*” at the beginning, end or both (but not in the middle) must be interpreted as a wildcard. The service must match strings case insensitive unless otherwise defined. In the case where a preceding “{” and ending “}” are used, any wildcards must be placed outside the “{}” (ex: “*{string}*”) . You can use “:”, “<”, “>”, “<:” and “>:” to match as ‘equal to’, ‘greater than’, ‘less than’, ‘greater than or equal to’ and ‘less than or equal to’ respectively. And finally, you can use “*” as the entire match string if you want all items within the search scope, but this must be done with caution as it will likely return a very large result set. Note that the entire match string must be properly escaped to be safely included in the URL when performing a search request via HTTP GET.
The following match fields and objects are defined by SCBP. All match fields and objects supported by a service must be included in the match element of the appropriate scope definition within the SCDP service description provided by that service. All field and object names are case insensitive and may only contain alphanumeric characters and one or more “_” characters. A service may define service-specific match fields and objects for each scope which are in addition to the ones defined by SCBP. The name of a service-specific match field or object should begin with “x_” and should not contain a period (“.”). The “id” match field is required to be supported by all SCBP services.
Match fields
The SCBP defined match fields are listed in the glossary.
Match objects
Match objects are different from match fields in that they represent a related item or a set of related items. The related item’s information can be referenced as a property of the match object. For example, songs may have a set of related contributors such that if you use “contributors.name:{Bob}+contributors.role:{writer}” in the match param, the result will include songs written by Bob. The SCBP defined match objects are listed below.
This represents the set of views of the item by all users of the service since the item was made available on the service. Properties of a view are: id, date, content_type, content_id, account_id, device_id. It may be further refined by using “views.date” to obtain only the number of views that occurred during a range of time. For example “match=views.date>:{2010-01-01}+views.date<:{2010-01-08}&result=views_count” will get you only the views of the item which occurred between Jan. 1 and Jan. 8.
contributors
Contributors are entities which have contributed to the production of the content. Properties of a contributor are: id, eid, name, role. A contributor can have the following roles: actor, director, studio, signer, writer, reader, publisher, producer, author.
downloads
The downloadable encodings.
streams
The streamable encodings.
images
The available images.
trickviews
The available trickviews.
subtitles
The available subtitles.
ad_map
Possible ad map.
drm
Possible drm data.
Using scopes as match objects
Child scopes can be used as match objects. For example “/search?scope=shows&match=episode.name:*{bad day}”. In this example the scope is shows, but the episodes scope is used in the match string.
count
Count can be used after . to indicate the count of a child scope. For example “/search?scope=shows&match=episodes.count>5″ with find any shows that have more than 5 episodes.
Allowed match fields and match objects within each scope:
The following are the lists of SCBP defined match fields and objects which are allowed within each scope. A service may support any of the following as well as any additional service-specific fields. Field names with the “.x” suffix indicate a match object where any field of that related item may be used. For example “channel.x” indicates that “channel.id”, “channel.name” and so on, may be used. In case of “images.x”, the “.x” suffix represents either “format” for format name or “url” for image url.
shows: id, name, description, format, audio_lang, subtitle_lang, channel.x, advisory, advisory_label, rating, categories.x, downloads.x, streams.x, images.x, copyright, type, web_site, contributors.x, subscription_price, subscribed, promotion, popularity, expires, favorite
volumes: id, name, number, description, number, format, audio_lang, subtitle_lang, channel.x, show.x, downloads.x, streams.x, images.x, published, advisory, advisory_label, rating, categories.x, complete, copyright, contributors.x, purchase_price, purchased, rental_price, rented, promotion, popularity, expires, favorite
episodes: id, name, number, guid, description, format, audio_lang, subtitle_lang, channel.x, volume.x, show.x, podcast.x, images.x, downloads.x, streams.x, duration, advisory, advisory_label, rating, categories.x, bookmarks.x, published, copyright, contributors.x, purchase_price, purchased, rental_price, rented, promotion, popularity, expires, favorite, resume
movies: id, name, guid, description, format, audio_lang, subtitle_lang, categories.x, bookmarks.x, channel.x, duration, advisory, advisory_label, rating, published, downloads.x, streams.x, images.x, contributors.x, copyright, web_site, purchase_price, purchased, rental_price, rented, promotion, popularity, expires, favorite, resume
music_videos: id, name, number, guid, format, audio_lang, channel.x, artist.x, album.x, downloads.x, streams.x, duration, advisory, rating, published, contributors.x, lyrics, copyright, purchase_price, purchased, rental_price, rented, promotion, popularity, categories.x, bookmarks.x, expires, favorite, resume
artists: id, name, format, audio_lang, rating, categories.x, downloads.x, streams.x, images.x, station.x, web_site, promotion, popularity, advisory, expires, favorite
albums: id, name, format, audio_lang, station.x, artist.x, downloads.x, streams.x, categories.x, images.x, duration, advisory, rating, published, copyright, contributors.x, purchase_price, purchased, rental_price, rented, promotion, popularity, expires, favorite
songs: id, name, number, guid, format, audio_lang, station.x, artist.x, album.x, downloads.x, streams.x, duration, advisory, rating, published, contributors.x, lyrics, copyright, purchase_price, purchased, rental_price, rented, promotion, popularity, categories.x, bookmarks.x, expires, favorite, resume
audio_books: id, name, guid, description, format, audio_lang, categories.x, bookmarks.x, downloads.x, streams.x, images.x, duration, advisory, rating, published, contributors.x, copyright, web_site, purchase_price, purchased, rental_price, rented, promotion, popularity, expires, favorite, resume
livefeeds: id, type, name, format, channel.x, station.x, downloads.x, streams.x, start, expires, categories.x, favorite
playlists: id, type, name, format, channel.x, station.x, downloads.x, streams.x, start, expires, categories.x, favorite
items: id, type, name, number, guid, format, audio_lang, subtitle_lang, playlist.x, channel.x, volume.x, show.x, station.x, podcast.x, artist.x, album.x, episode.x, song.x, movie.x, audio_book.x, downloads.x, streams.x, ad_map.x, duration, rating, categories.x
programs: id, type, name, format, channel.x, station.x, downloads.x, streams.x, start, expires, categories.x, episode.x, movie.x, music_video.x, song.x, audio_book.x, favorite
categories: id, type, name, format, audio_lang, subtitle_lang, download, streaming
bookmarks: id, type, name, number, guid, position, format, audio_lang, subtitle_lang, playlist.x, channel.x, volume.x, show.x, station.x, podcast.x, artist.x, album.x, episode.x, song.x, movie.x, audio_book.x, downloads.x, streams.x, ad_map.x, duration, rating, categories.x
favorites: id, type, name, number, guid, format, audio_lang, subtitle_lang, playlist.x, channel.x, volume.x, show.x, station.x, podcast.x, artist.x, album.x, episode.x, song.x, movie.x, audio_book.x, downloads.x, streams.x, ad_map.x, duration, rating, categories.x, resume
Contains a comma-separated list of match fields and objects properties which should be included in the result set of the response. This can be any of the allowed match fields for the scope of the search. For a detailed listing of allowed elements in the result for each scope, see the SCBP XML Schema. Additionally, aggregate fields are also defined for specific cases where aggregate data may be included in the result. Currently only count and sum are defined. Aggregate field names must take the plural form of a multi-match field (see below) with “_count” or “_sum” appended at the end of the element name. For example: “actors_count”. Any available aggregate fields must also be included in the SCBP capabilities. A service may also allow the inclusion of streams, downloads and ad_map in the result as an optimization to avoid additional SIMS actions to obtain the content media and/or ad media.
The id field must be included with each item in the search result, so it is not necessary to include it in the result parameter of the search request. In the result set of the query response, the service must only include the id field and any fields listed in the result element of the search request. If no result element is included in the request, then the service may assume a default set of fields for the result. If the result element is set to “*” then the service must return all possible fields supported by the service for the current scope. A service may also choose to support additional service-specific result fields.
Recursive matches:
Recursive match fields are match fields which apply to children of the item type searched. The service may determine which level of child is appropriate for the match. For example, if a client searches TV shows where format=hd, then the service may look for any episodes of any show in a channel having the format “hd”. If any episodes match, then that channel will be included in the result set. In some cases a field is recursively matched only if the service does not directly associate that field with the item type . For example, a service does not associate a category with each TV channel, but it does associate a category with each show. In that case a search for TV channels where category=3 would return any channels which contain shows that are in category 3. The following fields are classified as recursive match fields and elements:
format, audio_lang, subtitle_lang, downloads, streams, advisory, advisory_label, rating, category, contributor
In a search result, any field elements matched against children of the scope may include an optional “match” child element with a value equal to the name of the match object or scope which matched the field. For example, if the search scope is “channels”, but the field was actually matched against one of the episodes within that channel, the field element in the result set could include an attribute “match=episode”.
Multi-match fields:
Multi-match fields are match fields which may yield multiple values for each item in the result. In this case the element name must take the plural form (ie. “audio_langs”) and the value of the element in the result will be the set of values separated by commas. The following fields are classified as multi-match fields:
format, audio_lang, subtitle_lang, advisory, advisory_label
Note: In the case of a recursive multi-match field in the result set, a client must assume that at least one child of the item type matches one or more of the values returned for that field. For example, if a search for channels returns a channel which has a audio_langs field value of “eng, fre, jpn” then the device must assume that within that channel there is at least one episode of a TV show which is available in English, at least one which is available in French, and at least one which is available in Japanese.
limit* (integer)
Defines the max count allowed in a result set. If absent or empty, then the service may assume a default limit for the result.
sort* (string)
Uses the format “fieldname1:asc,fieldname2:desc,…” where ‘asc’ means ascending order (a to z) and ‘desc’ means descending order (z to a). The resulting sort must be in the order of the field names as listed. If the “:asc” or “:desc” suffix is not included with a field name, then the default sort direction is assumed by the service which is service specific. If no limit or sort element is used, then the service may assume a default limit and sort for the result.
language* (string)
Specifies the preferred language of the name and description in the response. This must contain one three-letter language code as defined in ISO 639-3.
0 Responses
Stay in touch with the conversation, subscribe to the RSS feed for comments on this post.