videdot : Data and message formats

Covers:

Be File System custom MIME types attributes/types/names
Messages that add-ons can respond to or send to provide enhanced functionality

This details how we store things locally. Individual plug-ins can always write things out differently. In particular the on-the-wire format when transferring information over the network won't typically use BeOS data structures, as that makes portability a nightmare.

By keeping all this open and clear, anyone else can build a better system using the code provided. It is more important to make something that works well, instead of hiding behind obfuscation, proprietary protocols and patents to try and remain cooler than the next guy.

Listings Feed

As the external feed, we are using the XMLTV format developed and coordinated by Ed Avis. We still need a common scheme for finding URIs to XMLTV listings, so that anyone can offer a listings service on the Web. At present the XMLTV project is focussed more on local processing of listings, and scraping them together from foreign Web sites. We're using the very handy XMLTV listings that Bleb offer for initial testing, but will switch to something that doesn't beat Bleb up in the longer term.

Filesystem Data Model

These are just the local formats, not what we would use on-the-wire. Note also that this is a preliminary spec, and might change up until the first open, public release, based on extra things we find we need in testing. Beyond that, the list may get added to, and old names may be retired, but the meaning of a particular, named field will be stable.

The types here are:

String: B_STRING_TYPE; UTF-8 encoded text. \n\n to separate paragraphs where allowed.
Time: B_TIME_TYPE; 64-bit microsecond time_t (shown as a textual representation in the examples below, for convenience).
Boolean: B_BOOL_TYPE; A bool, shown as 'true' and 'false' in the examples.

videdot Listing

application/x-vnd.videdot.listing

Attribute	Readable name	Type	Notes	Example
VID:channel	Channel	String	Matching a channel's `VID:channel_id`	`bbcone.bbc.co.uk`
VID:start	Start Time	Time		`21:00 2004-12-13`
VID:end	End Time	Time		`22:00 2004-12-13`
VID:title	Title	String		`Spooks`
VID:sub-title	Sub-title	String
VID:episode_name	Episode Name	String
VID:episode_number	Episode#	String	Rationalised XMLTV-style numbers (as in XMLTV, but with all whitespace stripped out and one-based counting). So the third series, last of ten episodes as a single part (in pure XMLTV this would be `2.9/10.0/1`). When we output XMLTV we get their format right.	`3.10/10.1/1`
VID:description	Description	String	Paragraphs allowed.	`Drama series about the British Security Service. Following up one of the numerous leads flooding into an overworked MI5, Danny and Fiona investigate a house they suspect is being used by North African terrorists. While the agents are installing a listening device, a gang of terrorists take them hostage.`
VID:pluscode	Videoplus+ code	String		`6145`
VID:credits	Credits	String	Multiple entries, each of the form `Post\tName\n`, a blank post for not knowing the role name.	`Olga Sosnovska Peter Fish Nicola Walker Shauna Macdonald Rupert Penry-Jones`
VID:links	Links	String	Multiple entries, each of the form `URI[\tTitle]\n` (the tab-title is optional, indicated by the square brackets)	`http://www.bbc.co.uk/drama/spooks/ BBC Programme page`
VID:prod_date	Date of Production	String
VID:clump_index	Clump Index	String	As per XMLTV's clumpidx, but 1-based counting
VID:language	Language	String		`en`
VID:country	Country	String	ISO country code	`GB`
VID:original_language	Original Language	String
VID:ad_breaks	Ad breaks	String	Timing points for the start and end of breaks, format as-yet undocumented.
VID:vid_present	Video Present	String	Note there is a substantial difference between this set to false and the absence of the attribute. It is quite usual for listing sources for Tv to omit this.
VID:vid_aspect	Aspect Ratio	String	x:y for possibly decimal x, y.	`16:9`
VID:vid_colour	Colour	Boolean		`true`
VID:aud_stereo	Stereo	Boolean
VID:aud_present	Audio Present	Boolean
VID:subtitles	Subtitles	Boolean	Just means out of band subtitles (e.g. teletext), may become a string to declare where out-of-vision they may be found
VID:subtitles_iv	In-vision subtitles	Boolean
VID:record_pri	Record Priority	16-bit Integer
VID:record_auth	Record Authorised	String	Notional user who flagged the programme to be recorded.	`baron`
VID:prev_shown	Previously shown	Boolean
VID:prev_shown_at	Previously shown at	Time	Matching the `VID:start`. Always have both or neither of the two `prev_shown_` attributes.
VID:prev_shown_on	Previously shown on	String	Matching a `VID:channel`

videdot Channel

application/x-vnd.videdot.channel

Attribute	Readable name	Type	Notes	Example
VID:channel_id	ID	String	XMLTV's RFC 2838-style ID	`skyone.sky.com`
VID:channel_name	Name	String	Human-readable name, may be more than one - `\n` separating them	`Sky One`
VID:logo_uri	Logo	String	URI for a logo in some sensible webbish format (preferably content negotiated eventually)
VID:tuning_info	Tuning info	String	May be several, `\n` separating them, each of the form `foo:val` where foo is a short alphanumeric id for the tuning system and val is a string detailing how to tune in, e.g. a channel number on the particular cable system. It's up to the recording app to get the work done, so it dictates what will appear here for a particular system.)	`ntl-excwc:30 skydigital:201`

videdot Recording

application/x-vnd.videdot.recording

To be determined later, once new recording is done. Broadly will be anything from application/x-vnd.videdot.listing, plus:

measures of the quality and type of recording (bitrate, format, &c);
information about the transmission path - to distinguish between a raw MPEG stream captured from digital cable versus analogue satellite feed, converted to RF then digitised by brand Y TV card. The more meta-information the better.

Video files

video/*

Although we can still use the the Recording meta-info files for archived recordings, now use the same attributes on any video file as well.

This allows us to interoperate with other Be apps, if we decide a collective format for the meta-data (as works well for audio files at present).

Message passing

Recording add-ons should accept these messages (constants are defined in videdot/Defs.h, so you should build against some sensible header files):

V_REC_START Start recording: Imminent start, but gives more precise time, should respond with V_REC_STARTED.
V_REC_CHANNEL Change channel: Will only occur while not recording (for simplicity). However, you may recieve an immediate sequence of V_REC_STOP, V_REC_CHANNEL, V_REC_START without waiting for response messages, since programmes which are back-to-back on different channels should not be clipped because of back-end processing. Just get on with starting the recording and send the responses slightly later if need be.
V_REC_STOP Stop recording: Should respond with V_REC_COMPLETED to the Scheduler, with details of the recording (format to be determined). It is the Scheduler's responsibility for updating or creating the meta-information on the recording file, since this is common for all recordings, no matter the recording application. A recording add-on may choose to add to the meta-data with things it knows from the transmission or settings itself.

The return codes above are for the ordinary (successful) case. Should any operation fail, the recording app should respond with V_REC_ERROR with code and message fields describing the error. A list of valid error codes will follow.

No comments yet. Add one.