Intro

So you just uploaded a shiny new .mp4 media file into your SCORM Cloud library, but now you need to add subtitles for hearing impaired learners or closed captioning in another language for international learners. How do you do that?

Since media files don't use a .zip package like a learning standard specific course, there are a few steps you'll need to follow in order to get your subtitles attached to your course. In this article, I'll outline these steps and highlight a few potential pitfalls so that you can be using subtitles and closed captioning in no time!

Adding and Attaching Subtitles

Step 1: Uploading the .vtt File

The first step you'll need to do is upload the subtitle file (in .vtt format) into SCORM Cloud. Alternatively, if your .vtt files are stored somewhere else and available via a public link, and you don't want them uploaded to SCORM Cloud, you can skip this step and move directly to step 2.

To upload the subtitle files onto SCORM Cloud, you'll want to use the UploadCourseAssetFile API method. Alternatively, you can use the ImportCourseAssetFile method, or one of the version specific variations of those methods if you're trying to set subtitles for a specific version of a course. Using these methods will ensure that not only will the subtitle files be stored alongside the .mp4 file, but also that our content access control measures will allow the player to load the subtitle files without any issue.

A couple of things to note with these methods: first, the "destination" parameter should include the filename, and should be relative to the course root. Since .mp4 files don't have a course structure from the unzipped package like a SCORM course would, this path could be whatever you want. But it's important to include the filename so that you know what values to use in step 2. For example, if you wanted to store your subtitle files in a "subtitles/" directory separated by language alongside the video, your destination would look something like the following:

destination: /subtitles/english/en.vtt

You'll also want to pay attention to the "updateAssetPolicy" value in your API call. If you haven't uploaded any subtitle files to this course before, the default value of "lax" is ok. However you can use one of the other options, "reject" or "strict", depending on how you want Cloud to handle updating a file if it already exists at that path.

Step 2: Attaching the Subtitles to the Course

Once the subtitle files are in place, it's time to attach them to the course so that Cloud's player knows what to load and where to load them from. This is done using the SetCourseConfiguration API method (again, you can use the version specific API method if you're looking to set this for a specific version of a course) to set the "ContentLangToUrl" setting.

This config setting takes an array of ContentLanguageDefinitions, which tell the player how to load these helper files, and where to load them from. You can set multiple languages of subtitles in a single call. A typical ContentLangToUrl value might look something like the following:

[
  {
    "label": "English",
    "srclang":"en",
    "src": "/subtitles/english/en.vtt",
    "default": true,
    "kind": "subtitles"
  },
  {
    "label": "French",
    "srclang": "fr",
    "src": "/subtitles/french/fr.vtt",
    "default": false,
    "kind": "subtitles"
  },
  ...
]

Out of these parameters, only "label" and "src" are required, which are the string that is displayed in the player to use that subtitle and the URL for the file to use for that set of subtitles respectively. Then there are the optional properties you can use to better categorize these values. "srclang" is the ISO language code associated with the language supported, "default" tells the player if that language should be the default for that course, and "kind" can either be "subtitles" or "captions" depending on what type of support file is used.

Step 3: That's It!

You're all set! Once you've done all of these, you should see captions in the menu of the video player similar to the following:

Now your video content can be enjoyed with subtitles and closed captions!

A Few Notes

Why No UI?

At the time of this article's writing, there isn't any way to upload and attach subtitles to a video course in the SCORM Cloud UI, it's only possible to do with our V2 API. However, we are in the process of updating our UI, and intend to add a place for uploading and attaching subtitles in that updated version.

Why Are My "src" Values Different When I Call GetCourseConfiguration?

After you set the ContentLangToUrl configuration setting for your course, a subsequent call to GetCourseConfiguration may have a modified value for the "src" property. You may notice a value like the following:

"src":"/content/courses/{appId}/{courseId}/{courseVersion}/subtitles/english/en.vtt"

SCORM Cloud automatically prepends the rest of the relative path needed to load your uploaded VTT file. Adding this path makes sure that the subtitles work for all types of launches, including sandbox and Content Vault launches.

Errors

If you have followed the steps outlined in this article and are seeing the above error when trying to launch your video file, then start by deleting the ContentLangToUrl setting and verifying that the subtitle file was uploaded to the correct course. Then you can try setting the ContentLangToUrl setting again to see if the video displays correctly. If you are still running into issues, please email us at support@rusticisoftware.com and we can help you figure it out!

 

As always, if you have any questions or concerns, feel free to reach out to support@rusticisoftware.com