Safari Documentation
Video
Safari Books Online uses a Content Delivery Network (CDN) to intelligently stream video content in the format and bitrate appropriate to the end user's device and bandwidth. The CDN is pretty flexible when it comes to file formats submitted, but with today's retinal displays and large monitors, it's best to provide your highest quality source files.
There are currently two ways to submit video content: via HTTPS in our browser-based CMS, or via FTP. For publishers with a high volume of video content and the ability to output metadata in XML format, we recommend using FTP for all video deliveries. For publishers with only occasional video submissions, or publishers who don't have an XML workflow, we recommend a hybrid of CMS and FTP: Use the CMS to input your metadata and create the TOC structure, and then use FTP to upload the clips.
File naming is the key to the video process: specific file naming conventions tell the system that a given clip goes with its "chapter" in the TOC, so pay special attention to the file naming section.
Closed captioning is supported in our player. We encourage the publisher to provide caption files, and those requirements are outlined later in this chapter. At Safari's discretion (generally based on the popularity of a given video title) we will transcribe captions for certain video titles.
Here are the components of a video book upload:
- One or more movie files (clips)
- metadata.xml containing author information, publication date, etc.
- book1.xml containing the TOC information
- Cover image
- (Optional) Closed Captioning files.
- (Optional) Related downloadable material (exercises, accompanying images, etc.)
Recommendations for Optimal Transcoding
Following is a list of all acceptable source file formats that our system will transcode:
- AVI
- FLV
- M4V
- MOV
- MP4
- MPG
- WMV
The recommendations that follow are not requirements; all submitted content will be handled to the best of the transcoding system’s ability.
The optimal input format is MP4 with H264/AAC encoding, of 1200kbps or greater, an aspect ratio of 16:9, and a width equal to or greater than 960 pixels.
Video file submissions are transcoded into more than 20 different formats for device delivery. Therefore the video file submissions should be of mezzanine quality. The encoding specifications below are recommended for best results.
Container: mp4
Video codec: h264
Audio codec: aac
Audio Channels: 2
Audio Sample Rate: 44100
Minimum Video kbps: 1200
Minimum Audio kbps: 128
Frames per second: 30
Key frame interval: 30
WARNING: Do not enable AAC+SSR (Scalable Sample Rate) or AAC+SBR (Sub Band Replication) on the audio stream. AAC+SBR is also known as HE-AAC.
WARNING: Video clips must contain sound—those that do not will error out during transcoding.
Table of Contents
Safari uses book terminology to define the table of contents (TOC) of a video title. Each video clip makes up a chapter (in book parlance), and, optionally, parts can be used to group the chapters. Parts cannot contain clips—only chapters can contain clips.
File Naming
The filename of the submitted video files should match the chapter id (otherwise known as linkid) referred to in the book1.xml file and the linkid in the safarimeta.xml file, along with a file extension appropriate to the video’s format. The filename convention is LINKID.ext, and the clips must be uploaded into the incoming/FPID folder so that the system knows which FPID to associate them with. Another supported naming format is FPID-LINKID.ext.
Here are a few additional file naming requirements:
- case sensitive
- contain only valid Windows characters
- can NOT contain any spaces
Audio-Only Support
Audio files can also be handled by our transcoding system. If an MP3 is submitted with a corresponding image, the system will transcode the MP3 and display the static image. The output video dimensions will be the same as the submitted graphic (+/- 1 pixel). The submission should consist of an mp3 file named as FPID-LINKID.mp3, and a corresponding image file of FPID-LINKID.jpg. The two will be combined into one MP4 file for web/mobile consumption.
Video Metadata.xml
All XML should be in UTF-8 encoding format. Metadata.xml contains the same information as non-video Safari content with the following additions:
Captions. This metadata element specifies whether movie files are provided with closed captioning information. Allowed values are Yes or No.
Video. The <video> element contains a <clip> element for every movie. The <clip> element describes the movie clip and contains a <file> element, and, optionally, a <description> element:
<video>
<clip linkid="chapter1" preview="yes">
<file url="/12345CMSDEMO/chapter1.flv" caption="/12345CMSDEMO/chapter1.dfxp.xml"/>
<description>This is a clip description for Chapter 1.</description>
</clip>
</video>
where
- linkid is a unique id for the movie (which is referenced in book1.xml as chapter id).
- preview is set to "yes" if this movie should be visible to users who have not purchased this video. Remember, at least one movie clip must be identified as preview material, viewable by users who are not logged into Safari.
- width, height, and duration are not required in submitted metadata because the transcoding system will populate the data. If provided, the data will be replaced by the transcoding system.
File. The <file> element is a child of the clip element and provides links to a movie file. The format of <file> is:
<file url="/12345CMSDEMO/chapter1.flv" caption="/12345CMSDEMO/chapter1.dfxp.xml"/>
where
- url is the movie file. It should start with “/FPID”. That is, a leading forward slash, followed by the FPID.
- caption is the optional closed captioning file. This attribute is only needed when caption files are provided. The filename convention is LINKID.dfxp.xml.
- format is no longer required in submitted metadata because the transcoding system will populate the data. If provided, the data will simply be replaced by the transcoding system. If provided, it must be either "QuickTime", "Flash", or "WindowsMedia" (case-sensitive).
Description. The optional <description> element is a child of <clip> and provides a description that is displayed accordion-style in the TOC. The format is:
<description>This is a clip description for Chapter 1. </description>
The video clip <description> element has a maximum of 1024 characters and no special encodings are supported. (The element is ASCII.)
Hidden. This is an optional standalone metadata element available for video titles only. Hidden video titles make it possible for publishers to upload video for use only in the context of a book. This video content will be available only from a book’s Extras tab and/or from inline links in the content of the book. Although you’re actually creating a standalone video title in this scenario, it will not be discoverable as a standalone product with its own catalog page.
<hidden/>
Hidden video is:
- Hidden from search.
- Hidden from category browse (even if the video is assigned to categories).
- Lacks a catalog page (can't be found by putting in a catalog page URL).
The video title is still a separate product with an FPID, and is still eligible for payments. See the Interactivity on Safari chapter for more information on how to use it and how to add inline links to video to your books.
Example video metadata.xml:
<safarimeta fpi="12345CMSDEMO">
<isbn/>
<edition/>
<rights>Copyright © 2011 Safari Books Online</rights>
<authorgroup>
<author>
<firstname>Molly</firstname>
<surname>Sharp</surname>
</author>
</authorgroup>
<pubdate>January 13, 2011</pubdate>
<publisher>
<publishername>Safari Books Online</publishername>
<imprintname>Safari Books Online</imprintname>
</publisher>
<description-short>
<para>
This is just a test video for <emphasis>the new CDN</emphasis>.
</para>
</description-short>
<msrp>25.00</msrp>
<points royalty="all">1</points>
<captions>No</captions>
<graphic role="large-cover" fileref="12345CMSDEMO_large.jpg"/>
<video>
<clip linkid="chapter1" preview="yes">
<file url="/12345CMSDEMO/chapter1.flv"/>
<description>This is a clip description for Chapter 1.</description>
</clip>
<clip linkid="chapter2">
<file url="/12345CMSDEMO/chapter2.mov"/>
<description>This is a clip description for Chapter 2.</description>
</clip>
</video>
</safarimeta>
Video book1.xml
All XML should be in UTF-8 encoding format. The book1.xml file contains TOC information. Each <chapter> maps to an individual movie file. <part>s may optionally be provided as an extra hierarchy level, in which the chapters live. Parts may not include clips; they merely provide organizational structure.
- Parts require ids even though they are not referenced.
- The chapter ids must match the corresponding linkid in metadata.xml.
- The part and chapter titles will be displayed as-is in the title’s TOC.
- Each <chapter> requires <para/> following the <title> tag.
For example, a book with chapters containing sections is represented as parts with chapters:
Example video book1.xml:
<book fpi="12345CMSDEMO">
<title>Sample Video Title for the New CDN</title>
<part id="part1">
<title>Chapter 1: Part Header</title>
<chapter id="chapter1">
<title> A Test Clip</title>
<para/>
</chapter>
<chapter id="chapter2">
<title> Another Test Clip</title>
<para/>
</chapter>
</part>
</book>
A book without a part hierarchy is similar:
<book fpi="12345CMSDEMO">
<title>Sample Video Title for the New CDN</title>
<chapter id="chapter1">
<title>Chapter 1: A Test Clip</title>
<para/>
</chapter>
<chapter id="chapter2">
<title>Chapter 2: Another Test Clip</title>
<para/>
</chapter>
</book>
Under Development. You can end a chapter title with the string “(Under Development)”, to indicate that the video clip will be loaded later. Then that video clip will not be required to be present and transcoded for presentation to SBO. In this case, there will not be corresponding ‘clip’ identification within metadata.xml.
Video Cover Image
For video titles, only one cover image is required. It should be a JPEG with a width of 400 pixels or more. The video cover should represent the subject matter, so please avoid using a picture of a DVD or a 3-D DVD box. It should be named FPID.jpg or FPID_large.jpg. The system will create the other sizes needed for display on Safari.
Closed Captioning Information
Closed Captioning data should be of DFXP format as defined in http://www.w3.org/TR/ttaf1-dfxp/. Each file is named according to the ‘linkid’ as found in the attribute of the metadata ‘clip’ element. The filename convention is LINKID.dfxp.xml.
When closed captions are supplied, the system adds the text of the closed captioning file to the book content to support full text search of the video clips.
Related Download Material (Extras for Video Titles)
The Companion Content/Extras chapter describes <relatedfiles> and how to specify related files—images, examples, etc. The process is the same for video titles as it is for non-video titles.
Video Upload Methods
There are two possible upload methods for video titles: 1) FTP / SFTP, and 2) HTTPS (web browser access to the video CMS). They can be used interchangeably—in other words, you can initially upload a video title using one method, and then update that same title using either method. For example, you could initially upload a video title via FTP, and later make edits to that title by accessing the CMS via a web browser.
FTP/SFTP Upload
Given a username and password, you may upload new and updated content via FTP or SFTP to the hostname of “cms.safaribooksonline.com”.
Content may be delivered via a zip file that includes all assets for the video book. The zip file should be named as the FPID of the book with the extension of “.zip”. The top level of the zip archive should contain a directory named as the FPID of the book. All assets should exist within this top‐level directory.
The FPID must begin with 5 digits followed by alphanumeric characters. There is a maximum of 20 characters for the FPID.
At a minimum, the initial upload zip file must contain a book1.xml, metadata.xml, and a cover JPG. While you need at least one clip for the final production, more clips can be added either to the zip or later in the process.
Each asset file should be named according to the FPID and LINKIDs described within the metadata. There are 7 file types:
- book1.xml—This xml file is always named as “book1.xml”. It describes the video’s table of contents.
- metadata.xml—This xml file is always named as "metadata.xml". It describes video metadata.
- FPID.jpg—This jpeg file is the cover image for the video.
- linkid.mp4—This is a video clip that references the chapter id within the associated book1.xml file.
- linkid.dfxp.xml—This is the caption data for the video clip in DFXP format.
- linkid.jpg—When building a video file from an mp3 file, this jpeg file is used as the static image of the video. An associated .mp3 file is required.
- linkid.mp3—When building a video file from an mp3 this file is used as the audio stream of the video. An associated .jpg file is required.
For example, a submission of a simple book of the FPID 12345CMSDEMO that includes two chapters with LINKID “chapter1” and “chapter2” is outlined below:
12345CMSDEMO.zip
--------------------------------------------------------
12345CMSDEMO/book1.xml
12345CMSDEMO/metadata.xml
12345CMSDEMO/12345CMSDEMO.jpg
12345CMSDEMO/chapter1.mp4
12345CMSDEMO/chapter1.dfxp.xml
12345CMSDEMO/chapter2.mp3
12345CMSDEMO/chapter2.jpg
12345CMSDEMO/chapter2.dfxp.xml
Uploading DFXP and MP3 files is not common. Most video collections consist of book1.xml, metadata.xml, FPID.jpg, and FPID-LINKID.mp4.
The uploading of an MP3 file requires that an associated JPG file is also uploaded. When both exist, a new video clip for the LINKID will be created that combines the two as a statical image video stream with the audio.
The zip file should be uploaded to the /incoming directory of the account.
After the zip file is uploaded, a text file named FPID.txt should be uploaded consisting of the string ‘update’. The existence of this file is required for ingestion of the zip file.
Individual assets may be incrementally updated by uploading these into a new directory within /incoming. This directory must be named as the FPID of the video book. The naming convention of the assets remains the same. For example, to update the cover graphic for the video book of the FPID of 12345CMSDEMO, you would create the directory /incoming/12345CMSDEMO and upload the graphic file as “/incoming/12345CMSDEMO/12345CMSDEMO.jpg”. Graphic files, captioning files, and video files may be updated in this manner.
If assets are uploaded without book1.xml and metadata.xml previously being loaded, the assets will not be loaded.
Although it’s acceptable to include the video clips in the zip file, it is usually more practical to upload the clip files directly to /incoming/FPID. This can be done before or after uploading the initial zip file containing the book1.xml, metadata.xml, and cover JPG. Files loaded directly to /incoming/FPID should NOT be zipped.
HTTPS Delivery (Accessing the CMS via Web Browser)
Given a username and password, you may log in to https://cms.safaribooksonline.com/.
You can access Help content for each section in the CMS by hovering your cursor over the Question Mark icon.
Upon logging in, you see two sections: “Videos” and “Clips”. Within “Videos”, you may create new video titles via the “Add New Video” link.
There are two panels of title lists, “Promoted to Safaridata” and “Pending”. “Promoted to Safaridata” is a list of titles that have been submitted for processing. The “Pending” panel consists of video titles that are not yet submitted. You may search for FPID, title, and author within the selected panel with the search input form on the header of the webpage. You may review and edit video titles via the pencil icon link in the rightmost column.
Within “Clips”, you may upload video clip content directly. If the video clip is to be associated with a video title, the correct FPID must be entered. After entering the FPID, the chapter selection menu will be propagated with the linkids that are associated with the video book. Select the appropriate linkid and choose the local clip file that you would like to upload.
If an existing FPID is known within the CMS, and a user uploads a clip that is already referenced by the metadata, then the clip will be picked up and transcoding begins.
If an existing FPID is known within the CMS and a user uploads a clip that is not referenced by the metadata then the clip will be picked up and will be put on hold until the linkid referenced by the clip filename is later defined by a metadata update or until the user manually associates the clip to a linkid via the CMS UI.
If an FPID is not known within the CMS and a user uploads a clip to the unknown FPID then the clip will not be picked up.
Previously, if a clip was uploaded with a filename that did not reference an existing linkid, the clip would be on hold until manual intervention.
If a clip is uploaded without an FPID, it will not be associated with a video book. These videos will be transcoded. After they are transcoded, URLs to stream the videos will be displayed on the Clips section under the heading of “Non-Associated Videos”.
If a clip is uploaded with an FPID but without a proper chapter linkid, you will need to return to the Videos page and edit the video title to associate the chapter with the link via the “Video Clip” selection menu as shown below. Click the Edit pencil icon next to each chapter to access the selection menu.
Promotion to the Staging Server
Once the system has received all the required fields including a minimum of one video clip, it begins the transcoding process. The transcoding process will take approximately 3x the total minutes of the video. When transcoding is complete, the video title moves from the Pending tab to the Promoted to Staging tab, and becomes available on the staging server.
If the video fails to promote to staging, you will want to check log details to learn of any errors. See the Logging section later in this chapter.
Testing Video Content on the Staging Server
These are the minimum testing requirements for video titles on Safari. Ensure the following:
- TOC links work
- All four sizes of the cover are present
- Chapter names match the actual video content
- The video clips play all the way through
- Title Overview is complete
- Additional files provided via the Extras tab are present
Promotion to the Production Server (Live)
Once you’ve verified that the video title is working properly on the staging server, you can promote it to the live server via uploading a promotion request file to ftp.bvdep.com as outlined in the Upload via FTP chapter. Please note that this promotion trigger file goes to a different FTP server than the one used to upload video content. Use the same promotion process and FTP credentials as for promoting books live on Safari.
Trigger files are uploaded to the /promote folder. The FPID.txt file must contain the keyword “promote”.
Video Title Acceptance
Safari’s QA team reviews each new title to confirm that the basic requirements have been met, including audio and video quality, functionality, and completeness. (See the Safari QA chapter for more details.) The QA team emails the publisher with the status of each promoted title.
Logging
Detailed logging is available in the CMS. When you edit a title on either the "Pending" or "Promoted to Staging" tab, click the Log Info link on the bottom right of the screen as shown here.
The same log is available here (replace the FPID): https://cms.safaribooksonline.com/rest/book/{FPID}/fullstatus?type=html
Or you can check the detailed log via this web link (replace the FPID): https://cms.safaribooksonline.com/rest/book/{FPID}/log?type=xml
If your title has failed to promote to staging, review the log for clips that may be corrupt (clip_corrupt/is_corrupt), missing (clip_missing/hasclip), or still transcoding (clip_istranscoding/istranscoding). If you find such clip(s), note the linkid and review the source clip in question to determine if any fixes need to be applied.
Logging is also available on FTP. Email callback notifications and API retrievals are also available; documentation is available upon request (msharp@safaribooksonline.com).
HTTPS/API Delivery
A RESTful interface is available to manage content. This interface can accept content updates for book1.xml, metadata.xml, graphic files, and captioning data. Video files must be submitted via FTP/SFTP. Documentation for API delivery is available upon request (msharp@safaribooksonline.com).