Skip to main content

Create videos with Video Editor SDK

This documentation shows an example of creating a single video using Video Editor SDK. To see each steps at a glance, take a look at Flow.

Requirements​

Create an empty RenderSession​

You can create a video by creating a RenderSession object. Each RenderSession represents single video, and after you create an empty RenderSession, you get RenderSession ID that can be used to load up the Shakr Editor.

Let's make a RenderSession based on TemplateStyleVersion ID that we have obtained from previous steps.

curl 'https://api.shakr.com/v2/render_sessions' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer SERVER_ACCESS_TOKEN' \
  --data-raw '{
    "title": "My New Video",
    "mapping": {
      "template_style_version_id": "TEMPLATE_STYLE_VERSION_ID"
    },
    "edit_token": true
  }'
{
  "render_session": {
    "id": "string" // RenderSession ID
    ...
  },
  "edit_token": "string" // Scoped access token that can only access this RenderSession
}

Response​

When a RenderSession is successfully created, RenderSession ID and Edit Token are returned.

  • RenderSession ID: Unique ID of the created RenderSession. As Shakr API does not create and manage users, you can save this ID to your database and tie it to your users.
  • Edit Token: Edit Token is a scoped access token that can only access this RenderSession. This token is used to call Editor SDK.
info

While it is possible to use server access token to access Video Editor SDK, it should be avoided as it can allow accessing other user's videos or abnormally increase API usage and cost. Use edit_token on Video Editor SDK whenever possible as it only has limited access to the current RenderSession. Please refer to Authentication documentation to learn more.

Adding sdk.js to Web Application​

You can install and use Shakr SDK products in various ways. While in this sample we're directly injecting <script> tag for a quick test, you can also use it by installing the npm package, which supports ES module syntax and TypeScript type annotations. For more information, please refer to Installation documentation.

To add Shakr SDK to your page, insert <script> tag of the SDK above the <script> tag that includes your application's code.

<body>
  ...
  <script src="https://sdk.shakr.com/sdk.js" defer></script>
  <!-- Your application js codes -->
</body>
info

For security, SDK requires HTTPS connections via Content Security Policy (CSP) headers. If you load SDK under HTTP connection, browser will prevent SDK from loading. You can use HTTPS server with self-signed SSL certificate on your local testing environment.

Create a ShakrEditor instance​

The sample code below shows how to create a ShakrEditor instance. Replace ACCESS_TOKEN with edit_token, and RENDER_SESSION_ID with an empty RenderSession ID that you have created.

createShakrEditor({
  access_token: 'ACCESS_TOKEN',
  render_session_id: 'RENDER_SESSION_ID'
}).then(function(editor) {
  // editor instance is created
});

Handle events​

ShakrEditor instance emits many events, and you need to handle few events that are necessary for Video Editor SDK usage. More information around events can be found on Handling Events documentation.

For example, if you want to handle an event named EVENT_NAME, you can use this code to add event listener to handle events.

editor.on('EVENT_NAME', (...) => {
    ...
});

Launch an editor​

You can launch an editor by using .launch() function on ShakrEditor instance. After loading the editor, load event will be called.

// Optional: Event handling when the Video Editor is open
editor.on('load', () => { ... });

// Launch the Video Editor
editor.launch();

Close editor manually​

While the editor closes automatically when the video editing is finished, you can close the editor manually with .close() function.

After calling .close() function, confirm_close event will be emitted when there are unsaved changes. After confirming with the user, you can use .close(true) function to close the editor.

// Close the editor (confirm_close event may be called)
editor.close();

// Sample handling on confirm_close event logic
if (window.confirm('Any progress that has not been saved will be deleted. Would you like to continue?')) {
  editor.close(true);
}

Knowing when video is ready​

There are two ways to know when video is ready. You can select the method based on your use case.

1. Use wait_rendering option​

  • No additional server-side code needed.
  • Render progress is displayed inside the editor.

2. Use webhook​

  • User does not have to keep the browser open until the render finishes.
  • Use when you want to limit downloads, as the video URL is not exposed to the client.

In this guide, we'll use wait_rendering method as it doesn't require additional server-side code. Please refer to webhook to learn more about using webhooks.

Add wait_rendering: true option when creating a ShakrEditor instance. When finish event is emitted, it will contain a URL for video download.

const editor = await createShakrEditor({
    ...
    wait_rendering: true
})
.on('finish', ({ video_download_url }) => {
    // Handle video url
    // i.e. Integrating video player for playback, or download video
    ...
});

Sample code​

Using all the essential features above, you can write the code like below to integrate Video Editor SDK.

const editor = await createShakrEditor({
    access_token: 'ACCESS_TOKEN',
    render_session_id: 'RENDER_SESSION_ID',
    api_url: 'https://api.shakr.com/v2',
    wait_rendering: true
})
.on('load', () => {
    // Editor is loaded successfully, and RenderSession information is loaded.
    // User can make the video from inside the editor.
    console.log('User can start editing render session ' + editor.render_session_id);
})
.on('confirm_close', () => {
    if (window.confirm('Any progress that has not been saved will be deleted. Would you like to continue?')){
        editor.close(true);
    }
});
.on('finish', ({ video_download_url }) => {
    // wait_rendering is true, which means finish event will be called after the render is complete.
    console.log('User has finished editing render session ' + editor.render_session_id);
    console.log('Video url: ' + video_download_url);
})
.launch();

Congratulations, you have successfully integrated Video Editor SDK to your web application! 🎉



More features of Video Editor SDK​

There are more features and options you can use to customize Editor SDK experience. Use these extra features to show custom media library to users,make it on-brand, and more.

Troubleshooting​

Refer to Errors documentation to learn more about errors you may encounter.