File Requirements

Last updated: 2024-02-28

To submit a video, you must load a cover, video clip(s), and a metadata file. Closed captioning files are encouraged and can also be included with your video submission.

Cover

For video titles, only one cover image is required. The system will create the other sizes needed for display on the O’Reilly Learning platform. The specs are as follows:

  • .jpg and .png images are accepted. Other formats will fail QA.

  • Minimum width of 400 pixels

  • RGB or CMYK color encoded

  • File named FPID.jpg or FPID.png

The video cover should represent the subject matter, so please avoid using a picture of a DVD or a 3-D DVD box.

Video Clips

Video file submissions are transcoded into multiple formats for various devices and network conditions. Therefore video file submissions should be of pristine quality. The minimum encoding specifications are listed here. Using higher quality encoding produces better results:

  • Container: mp4

  • Video codec: h264

  • Minimum Video kbps: 5,000

  • Frames per second: 30

  • Key frame interval: 30

  • Audio codec: aac

  • Audio Channels: 2

  • Audio Sample Rate: 44100

  • Minimum Audio kbps: 128

Warning

  • Do not enable AAC+SSR (Scalable Sample Rate, also known as AAC+SBR) or AAC+SBR (Sub Band Replication) on the audio stream.

  • Video clips must contain an audio track. Clips that do not include an audio track will fail to ingest.

16:9 Aspect Ratio (Preferred)

  • 1280 pixels in width

  • 720 pixels in height

  • 5,000 kbps Bitrate

Important
 If either or both width and height dimensions are not exact, both must be evenly divisible by 16.

4:3 Aspect Ratio

  • 1280 pixels in width

  • 960 pixels in height

  • 5,000 kbps Bitrate

Important
 If either or both width and height dimensions are not exact, both must be evenly divisible by 16.

Alternative Containers

We strongly prefer the MP4 video container, but AVI, MOV, M4V, MPG, and WMV will be handled to the best ability of the transcoding system.

Formats other than MP4 may take longer to process and result in degraded video and audio quality. Providing a higher bitrate is fine; however, it will take longer to transcode.

Accessibility Guidelines

Our membership is diverse, and we strive to support learning needs and preferences across a wide variety of content formats and devices. We recommend that uploaders strive for AA-level conformance per the W3C’s Web Content Accessibility Guidelines (WCAG).

Before uploading your content, please review this page for an overview of the accessibility features of the O’Reilly Learning Platform and some tips for making accessible content.

Audio-Only Support

Requirements and guidelines for audiobook works are identical to that for video works with the following exceptions:

  • The declared format should be audiobook rather than video.

  • Content files in MP3 format are accepted.

If you have questions about submitting audio-only titles, please email the Content Team.

Metadata

The metadata XML file tells our ingestion system about your video, including editorial details about the work as whole (such as title and author) and details about the specific clips.

The metadata file must be named FPID.xml. Following is a list of elements presented in the order they should appear in a metadata file. Elements set in red are required.

XML Header

The following XML version header must be included at the top of each metadata file:

<?xml version="1.0" encoding="utf-8"?>

<safarimeta>

The <safarimeta> tag is the first tag after the header and is required in all metadata files submitted to ingestion. This tag has two attributes that help us identify and classify the content.

FPI

The fpi attribute (the Formal Public Identifier, more commonly referred to as the FPID) is the official designation for the work in the O’Reilly Learning platform. It is typically the ISBN13 without hyphens. For content that has no ISBN, the publisher should assign one. If you are unsure or need help to create FPIDs, email the Content Team and we’ll be happy to help.

In addition, FPIDs must:

  • be unique

  • be at least 5 characters in length

  • begin with 5 leading digits

  • NOT begin with 0 or 66666

  • NOT contain more than 19 characters

  • NOT contain punctuation

  • all alphabetical characters must be UPPERCASE

For example:

<safarimeta fpi="12345ABC90123"

Format

The format attribute of the <safarimeta> tag defines the type of content being submitted. For this guide, we’re only concerned with video and, based on similarity, audiobook.

Important
 Using the incorrect format when submitting content will cause it to fail ingestion so please make sure to tag all of your submissions correctly.

<isbn>

<isbn> is the true 13-digit ISBN, including hyphens. No spaces should be included:

<isbn>978-1-4919-0188-5</isbn>

<title>

A <title> element is required in metadata. Place it immediately following the <isbn> element, for example:

<isbn>978-1-4919-0188-5</isbn>
<title>JavaScript Cookbook, 2nd Edition</title>

The following requirements ensure consistent title presentation in the UI:

  • Do not use all caps.

  • Do not move the words "A", "An", and "The" to the end of the titles. The system ignores these words in alphabetical sorts.

Yes:

<title>The Holy Grail of Network Storage Management</title>

No:

<title>Holy Grail of Network Storage Management, The</title>

Edition

Please provide the edition number at the end of the title. For example:

<title>The Holy Grail of Network Storage Management, 2nd edition</title>

  • Use the number (2nd edition) instead of the word (Second edition) in <title>.

  • Don’t use 1st edition identifiers. This creates confusion for users who see this and assume that there is a 2nd edition available, which is not always the case.

You should also provide the edition number as a numeric value in the <edition> tag (see <edition>).

Conference Videos

If your video is primarily a recording of live events like conference sessions, please include the name and year of the conference in the video’s <title> element. If your conference video includes different speakers as different clips, please be sure the speaker’s name is listed either in the clip <title> or the clip <description>.

<language>

<language> identifies the language of a video. For example, a publisher would include:

<language>en</language>

or:

<language>de</language>

If the tag is absent from the metadata, the system will automatically assume the work is in English.

The following languages are currently supported:

  • Chinese Simplified (zh-hans)

  • Chinese Traditional (zh-hant)

  • Dutch (nl)

  • English (en)

  • French (fr)

  • German (de)

  • Italian (it)

  • Japanese (ja)

  • Korean (ko)

  • Polish (pl)

  • Portuguese (pt)

  • Russian (ru)

  • Spanish (es)

Language codes follow ISO 639-1.

<edition>

Edition is used to differentiate multiple editions of the same video in a list of titles. <edition> should use numerals, for example 1, 2, etc.

<edition>2</edition>

<authorgroup>

An XML group named <authorgroup> should appear next in your metadata. This group can include  <author>, <firstname>, <surname>, <othername>, <authorblurb> sub-tags, as desired:

<authorgroup>
    <author>
        <firstname>Jason</firstname>
        <surname>Hamon</surname>   
    </author>
</authorgroup>

<author>

<author> must be repeated for each author or presenter in the video and should follow with <firstname> and <surname>. You can also include a middle name or middle initial using <othername>. No extra spacing or punctuation should be included; for example, there is no need to include spacing to separate multiple authors.

Non-human authors should be coded as:

<author>
    <othername>Hamon Press</othername>
</author>

Following are examples of how author elements are rendered.

  1. Where the <othername> contains pre-expanded content that should be rendered as-is. For example:

    <author>
    <firstname/>
    <surname/>
    <othername>Hamon, Jason</othername>
</author>

    Should render as: Hamon, Jason

    Empty tags may be ignored.

  2. Where the author has a middle name or initial. For example:

    <author>
    <firstname>Tom</firstname>
    <surname>Savage</surname>
    <othername>V.</othername>
</author>

    Should render as: Tom V. Savage

    Note that the rendering order may be different than the tag order within the author element.

<authorblurb> is an optional element. It may be provided for each individual author (i.e., within the <author> element) or once per book. If only one per book is provided, the URL attribute should point to a page containing information on all authors for a particular book:

<authorblurb url="http://wherever"/></authorgroup>

The ingestion engine will always try to normalize the name into the appropriate tags. If you add an <othername> that looks like a human name like:

<othername>Jason Jonathan Hamon</othername>

The ingester will break it apart into the <firstname> <othername> <surname> tags as appropriate. This can produce unintended results, so you should always use the appropriate tags for their respective name parts and only use <othername> with an associated role or as a company name.

<pagenums>

For video, <pagenums> is used to capture the run-time of the video in seconds:

<pagenums>3600</pagenums>

If you don’t know the correct length of the video work, you can use 0 on initial upload rather than the actual value. When we process the clips, we calculate the length of each clip and add them together to populate that field. Subsequent uploads should use the correct length (the generated metadata can be downloaded from the portal UI).

<rights>

The <rights> tag contains the copyright line for the video. This must include the copyright symbol (©), year, and name of holders. Don’t include trailing punctuation.

<rights>Copyright © 2010 Pearson Education, Inc.</rights>

or:

<rights>© 2008 Course Technology, a part of Cengage Learning</rights>

<pubdate>

<pubdate> is the video’s date of publication. Spell out the month in full:

<pubdate>April 16, 2015</pubdate>

If only the publication month is available, use the first of the month, for example:

<pubdate>April 1, 2015</pubdate>

<copyright_year> is the video’s year of publication, given as the four-digit year:

<copyright_year>2012</copyright_year>

<publisher>

The publisher XML group specifies the name of the publisher and imprint for the video.

<publishername> is the name of the publisher’s division responsible for the publication of the video. This field determines the publisher name displayed to users on O’Reilly Learning so it should represent the brand. It’s typically the same name as displayed on Amazon catalog pages.

<publisher>
    <publishername>O'Reilly Media, Inc.</publishername>
    <imprintname>O'Reilly Media</imprintname>
</publisher>

<safari-classification>

Classification is required for all video submissions to help users find specific types of video products.

These are product-level classifications, so choose the classification that most closely applies to the whole video title. Each video submission must include only one of the following:

course

lesson-style formats where one or more teachers instructs the learner about a specific subject in a structured, procedural fashion, often with the use of worked examples.

<safari-classification>
    <class scheme="safari-classification">course</class>
</safari-classification>
webcast

a capture of a live event that took place online, often comprised of a screenshare and audio recording.

<safari-classification>
    <class scheme="safari-classification">webcast</class>
</safari-classification>
interview

recordings where the predominant format is that of question and answer between one or more interviewers and one or more interviewees.

<safari-classification>
    <class scheme="safari-classification">interview</class>
</safari-classification>
conference

recordings of live conferences.

<safari-classification>
    <class scheme="safari-classification">conference</class>
</safari-classification>
certification

this is for videos in which the primary purpose is for certification or to prepare the viewer for a certification exam.

<safari-classification>
    <class scheme="safari-classification">certification</class>
</safari-classification>

For portal users, this field is shown as “Safari classification” and your choices are in a drop-down list. Note that the first four options—abstract, article, audiobook, and journal—are not applicable classifications for submissions with a video format.

If your video doesn’t neatly fit into webcast, interview, conference, or certification, please default to course or contact the Content Team.

<description-short>

The contents of the <description-short> field are properly formatted XHTML of an abstract of the title. HTML and plain text are also accepted. This content will appear on the title’s catalog page in the user interface.

<description-short>
    <p>Description goes here</p>
</description-short>

HTML markup can be used in <description-short>, provided that it is enclosed in a CDATA section and within a CDATA tag:

<description-short>
    <![CDATA[ ANY HTML ]]>
</description-short>

Please note the following guidelines for using HTML markup for descriptions:

  • The CDATA section and tag should be used even with valid, well-formed HTML.

  • Some HTML elements are reserved by the system and not allowed as part of description ingestion. Most notably, h1 and h2 elements cannot be used. However, h3 through h6 elements may be used to structure thorough descriptions if desired.

  • Character entities are supported, but numeric is preferred (e.g., &#169; instead of &copy; for the copyright sign); ampersands must be encoded &amp;.

Note

Unicode characters, as used by "smartening" punctuation, often translate badly when ingested. The most common errors are:

apostrophe

Use the ' key or &apos;. Single quotation and accent marks cannot be used.

quotation

Use the " key or &quot; to open and close quotes. Smart quotes, left and right double-quotation cannot be used.

em dash

Use &mdash;. There is no substitute, however you may use multiple hyphens. For example ---

en dash

Use &ndash;. There is no substitute, however you may use multiple hyphens. For example --

<msrp>

This tag contains the publisher’s suggested retail price of the title, expressed in U.S. dollars, with two decimal places and without the dollar sign ($). If no print version is available, use the retail price of the electronic version. The PSRP is the retail price and not the institutional/library price. This field cannot be left empty nor can it be set to 0.00. O’Reilly Learning does not accept content that is freely available elsewhere in the market, with few exceptions.

<msrp>29.99</msrp>

The <relatedfiles> element is optional and is used for links to companion material, reference material, or other resources you want to make available to users. The links are displayed under the Resources tab on the video player page.

There are several flavors of <relatedfiles> links:

Errata Page

unpublished errata for the title

Publisher Support

your Contact Us page

Publisher Website

your home page

Supplemental Content

a page where users can find companion material referenced in the title e.g., code examples

Other

anything else you want to make available

Under the relatedfiles element are several sub-fields:

<filegroup>
    <description>
        <cdata>Supplemental Content</cdata>
    </description>
    <ulink url="http://examples.oreilly.com/0636920028154/">Supplemental Content</ulink>
</filegroup>

You’ll tell us what kind of link it is in the description and the link text. An entry for a Publisher Website link would look like this:

<filegroup>
    <description>
        <cdata>Publisher Website</cdata>
    </description>
    <ulink url="http://oreilly.com/catalog/0636920028154">Publisher Website</ulink>
</filegroup>

Include multiple <filegroup>s for multiple links:

<relatedfiles>   
   <filegroup>
      <description>
        <cdata>Publisher Website</cdata>
      </description>
      <ulink url="http://oreilly.com/catalog/0636920028154">Publisher Website</ulink>
    </filegroup>
    <filegroup>
      <description>
        <cdata>Errata Page</cdata>
      </description>
      <ulink url="http://oreilly.com/catalog/0636920028154/errata">Errata Page</ulink>
    </filegroup>
</relatedfiles>

<video>

The <video> element contains a <clip> element for every segment in the work.

<clip>

The <clip> element describes the video clip and applies the clip title. The <description> element is optional:

<video>
    <clip linkid="chapter1" preview="yes" title="Chapter 1">
        <description>This is a clip description for Chapter 1.</description>
    </clip>
</video>

where:

  • linkID is a unique id for the clip (this will be re-used in the <tableofcontents> portion of the FPID.xml as the chapter ID.

  • preview is set to "yes" if this segment should be visible to users who have not purchased this video. Remember, for videos containing more than one clip, at least one segment clip must be identified as preview material, viewable by users who aren’t logged in to O’Reilly Learning.

  • The width, height, and duration attributes are no longer required in submitted metadata and should be omitted because the transcoding system will populate the data. If provided, the data will be replaced by the transcoding system.

More information about linkID!

In combination with the FPID, linkIDs uniquely identify video clips everywhere in the Content Management System. As such they are extremely "fragile." To avoid extreme disruption of video content, you must obey the following rules when working with video submissions:

  • NEVER change the linkID of a clip.

  • UPDATING a clip: You MUST re-use the same linkID.

  • ADDING a clip: You MUST use a NEW linkID. NEVER RE-USE an existing linkID.

  • REMOVING a clip: Leave the linkID out of the metadata, in both the <video> and <tableofcontents> sections.

  • The linkID does not represent the order of playback. If you use linkID a0001 in one place and a0002 in another place, we’ll not automatically assume that a0001 is supposed to play before a0002.

  • See File Naming for best linkID practices, even if you aren’t uploading with the SFTP.

Simple linkIDs generally work best when possible. Examples of good linkIDs are:

  • a0001

  • video123456

  • L1_C1

  • strata_001

Examples of bad linkIDs:

  • This_is_the_complete_title_of_the_video_clip (too long)

  • a001 (too short, must be at least 5 characters beginning with an alpha)

  • L1 C1 (space in the linkID)

  • 000001 (should not start with "0")

  • video&12345 (has a non alphanumeric character)

<description>

The <description> element is a child of <clip> and provides a location to add text below the video player window for each clip. 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.)

Tip
 Want to boost discoverability of your video? Including description text at the clip level will help users locate your videos, so use the clip description to explain what the user can expect to learn from the clip.

<tableofcontents>

O’Reilly 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. Part IDs cannot have a clip assigned to it—only chapter IDs can have a clip designation.

The table of contents is used to determine 1) the playback position of each clip in your video series and 2) creates the table of contents links on the overview and playback pages. To specify the playback order of the clips in the work, simply place the ToC elements in the order you want them to be in.

Each <chapter> maps to an individual movie file. Parts—as <part>—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 the <video> tag above.

  • The part and chapter titles will be displayed as-is in the title’s ToC.

For example, a video with chapters containing sections is represented as parts with chapters:

<tableofcontents fpi="12345METADATA">
    <part id="p001" seq="1">
        <title>Part 1 - This is Part One</title>
        <chapter id="c001" seq="2">
            <title>Lesson 1- This is Lesson One</title>
        </chapter>
    </part>
    <part id="p002" seq="3">
        <title>Part 2 - This is Part Two</title>
        <chapter id="c002" seq="4">
            <title>Lesson 2 - This is Lesson Two</title>
        </chapter>
        <chapter id="c003" seq="5">
            <title>Lesson 3 - This is Lesson Three</title>
        </chapter>
    </part>
</tableofcontents>

A video without a part hierarchy is similar:

<tableofcontents fpi="12345METADATA">
    <chapter id="c001" seq="1">
        <title>Lesson 1- This is Lesson One</title>
    </chapter>
</tableofcontents>

</safarimeta> (End Tag)

An end tag must be used to indicate the conclusion of the FPID.xml file:

</safarimeta>

Sample Metadata File 

<?xml version="1.0"?>
<safarimeta fpi="12345METADATA" format="video">
    <title>Sample Metadata</title>
    <rights>© Safari Books Online 2015</rights>
    <copyright_year>2015</copyright_year>
    <msrp>42.00</msrp>
    <edition>1</edition>
    <pubdate>February 2, 2015</pubdate>
    <isbn>978-1-4919-0172</isbn>
    <pagenums>1234</pagenums>
    <language>en</language>
    <authorgroup>
        <author>
            <firstname>Sally</firstname>
            <surname>Safari</surname>
        </author>
    </authorgroup>
    <publisher>
        <publishername>Safari Books Online</publishername>
        <imprintname>Safari Books Online</imprintname>
    </publisher>
    <safari-classification>
        <class scheme="safari-video-classification">course</class>
    </safari-classification>
    <description-short>
        <p>Welcome to the wonderful world of sample metadata. This sample metadata will get you started on the right path to making sure your submissions to the O'Reilly Learning platform are as accurate as possible and can be uploaded with as little effort (and headache) as possible.</p>
    </description-short>
    <relatedfiles>   
         <filegroup>
             <description>
                 <cdata>Publisher Website</cdata>
             </description>
             <ulink url="http://oreilly.com/catalog/0636920028154">Publisher Website</ulink>
         </filegroup>
         <filegroup>
             <description>
                 <cdata>Errata Page</cdata>
             </description>
             <ulink url="http://oreilly.com/catalog/0636920028154/errata">Errata Page</ulink>
         </filegroup>
    </relatedfiles>
    <video>
        <clip linkid="c0001" preview="yes" title="Lesson 1- This is Lesson One">
            <description>This is the first lesson of many aimed at helping you learn this technology that the video is  about.</description>
        </clip>
        <clip linkid="c0002" preview="no" title="Lesson 2 - This is Lesson Two">
            <description>Now that you've received an introduction to the program, lets dig a little deeper.</description>
        </clip>
        <clip linkid="c0003" preview="no" title="Lesson 3 - This is Lesson Three">
            <description>By now you are well on your way to becoming an expert but lets cover a few more things first.</description>
        </clip>
        <clip linkid="c0004" preview="no" title="Conclusion">
            <description>Congratulations on becoming an expert.</description>
        </clip>
    </video>
    <tableofcontents fpi="12345METADATA">
        <part id="p001" seq="1">
            <title>Part 1 - This is Part One</title>
            <chapter id="c0001" seq="2">
                <title>Lesson 1- This is Lesson One</title>
            </chapter>
        </part>
        <part id="p002" seq="3">
            <title>Part 2 - This is Part Two</title>
            <chapter id="c0002" seq="4">
                <title>Lesson 2 - This is Lesson Two</title>
            </chapter>
            <chapter id="c0003" seq="5">
                <title>Lesson 3 - This is Lesson Three</title>
            </chapter>
        </part>
        <part id="p002" seq="6">
            <title>Part 2 - Conclusion</title>      
            <chapter id="c0004" seq="7">
                <title>Conclusion</title>
            </chapter>
        </part>
    </tableofcontents>
</safarimeta>

Closed Captioning Information

You can greatly improve the discoverability and accessibility of your videos by including transcripts.

Source Files

Closed Caption files must be in either of two formats:

Formatting Conventions

  • Files must use UTF-8 encoding. Other formats, including UTF-8-BOM and ANSI are not supported and will fail at ingestion.

If you need assistance or clarification, please feel free to contact the Content Team.