Add Subtitles

This tutorial is for adding multi language subtitles via code.

Adding a single language subtitles can be done via Eko Studio without the need for custom code.
For more info please see Eko Studio’s Node Subtitles guide.

Using Config

There are two ways to add subtitles to an Eko video using the subtitles plugin.
The first, is by simply passing a subtitlesMap configuration object at plugin’s init:

// playerOptions.json
{
    "plugins": {
        "subtitles": {
            "subtitlesMap": {
                "node_a": {
                    "en-US": "url/to/node_a.en-US.srt",
                    "es-ES": "url/to/node_a.es-ES.srt"
                },
                "node_b": {
                    "en-US": "url/to/node_b.en-US.srt",
                    "es-ES": "url/to/node_b.es-ES.srt"
                }
            }
        }
    }
}

However, for a large project with many nodes/languages, this config can get quite big and difficult to write and maintain. This guide focuses on a second approach for adding subtitles - using a naming convention and the attach API.

Using Naming Convention + API

First, if you haven’t done so already, checkout a local copy of your Eko Studio project. Once the project is checked out, let’s create a src/assets/subtitles folder that will hold all of our SRT files. The filenames must conform to the following naming convention: [NODE_ID].[LANGUAGE_CODE].srt.

Our project folder structure should look similar to this:

|-- src
    |-- _eko_
    |-- assets
    |   |-- subtitles
    |       |-- node_beginning_9936df.en.srt
    |       |-- node_beginning_9936df.es.srt
    |       |-- node_not_to_be_9e3d8d.en.srt
    |       |-- node_not_to_be_9e3d8d.es.srt
    |       |-- node_to_be_5fcdc2.en.srt
    |       |-- node_to_be_5fcdc2.es.srt
    |       ...
    |-- js
    |   |-- app.js
    |-- templates

Now that we have our SRT files in place, all that’s left is to write the code that ties it all together.
Our code will:

• Iterate over all the SRT files
• Parse out the node ids and the language codes from the filenames
• Attach each SRT file to the relevant node using the player.subtitles.attach() API

Let’s edit our src/js/app.js file to include the following code:

export default function onReady(player) {
    // Init the subtitles plugin if not initialized
    if (!player.subtitles) {
        player.initPlugin('subtitles');
    }

    // Behind the scenes, eko-cli uses webpack to package our project.
    // The following code uses some webpack trickery. For more info, see:
    // https://webpack.js.org/guides/dependency-management/#require-context
    const SUBTITLES_WEBPACK_REQUIRE_CONTEXT =
        require.context('../assets/subtitles', false, /^.*\.srt$/);

    // Find all SRT files in 'src/assets/subtitles' (non-recursive).
    // The resulting value will be an array of filenames, for example:
    // ['node_beginning_9936df.en.srt', 'node_beginning_9936df.es.srt', ...]
    const SUBTITLES_FILENAMES =
        SUBTITLES_WEBPACK_REQUIRE_CONTEXT
            .keys()
            .map(filename => filename.substr(2));

    // All our subtitles filenames must adhere to the 
    // following naming convention: [NODE_ID].[LANG_CODE].srt
    const FILENAME_REGEX = /^(.*)\.(.*?)\.srt$/;

    // Iterate over all SRT files
    SUBTITLES_FILENAMES.forEach((filename) => {
        // Parse the node id and language code from filename
        const regexResults = filename.match(FILENAME_REGEX) || [];
        const nodeId = regexResults[1];
        const langCode = regexResults[2];

        // Verify that parsing was successful
        if (!nodeId || !langCode) {
            console.error(`Could not parse SRT filename "${filename}"`);
            return;
        }

        // Verify that node exists in repository
        if (!player.repository.has(nodeId)) {
            console.error(`Can't attach "${filename}": "${nodeId}" missing`);
            return;
        }

        // Let's attach the SRT file to the node!
        player.subtitles.attach(nodeId, {
            [langCode]: SUBTITLES_WEBPACK_REQUIRE_CONTEXT(`./${filename}`)
        });
    });
}

We should now be able to test our subtitles in action by running eko studio test.
Once we verify everything works as expected (i.e. subtitles are displayed and there are no console errors), we can stage, commit and push our changes.

For the sake of simplicitly, we’ve put all the code in our src/js/app.js file, but you may want to break it out into a separate module that’s in charge of loading/attaching the subtitles. The src/js/app.js module can call that module and pass it a reference to the player.