Creating audio tracks

Apps can add audio tracks to a user's design. These audio tracks play while the user is presenting their design and when the design is exported as a video.

The user experience

When an app creates an audio track, the audio file is uploaded to the user's media library.

The user's media library has a storage quota. If the user has a Canva Pro account, their storage quota is 1TB. Otherwise, their storage quota is 5GB. If the user exceeds the storage quota, they'll see an error.

The audio track itself appears in the design's timeline.

Supported audio formats

Apps can add the following types of audio to a user's design:

The maximum size of an audio file is 50MB.

How to create audio tracks

Step 1: Enable the required permissions

In the Developer Portal, enable the following permissions:

• canva:design:content:write
• canva:asset:private:write

In the future, the Apps SDK will throw an error if the required permissions are not enabled.

To learn more, see Configuring permissions.

Step 2: Upload an audio file

Import the upload method from the @canva/asset package:

import { upload } from "@canva/asset";

Call the method, passing in the options shown here:

const result = await upload({
  type: "audio",
  title: "Example audio",
  url: "https://www.canva.dev/example-assets/audio-import/audio.mp3",
  mimeType: "audio/mp3",
});

When uploading audio, the URLs must be exposed via the internet and available to Canva's backend, as Canva needs access to the URLs to download them. This means you can't use localhost URLs.

The upload method returns an object that contains a ref property:

console.log(result.ref);

This property contains a reference, which is a unique identifier that points to an audio asset in Canva's backend. An app can use this reference to interact with the file — even while it's uploading.

Step 3: Add the audio track to the design

Import the addAudioTrack method from the @canva/design package:

import { addAudioTrack } from "@canva/design";

Call the method, passing in the options shown here:

await addAudioTrack({
  ref: result.ref,
});

The only required property is the ref property.

Additional considerations

• All audio files must comply with Canva's Acceptable Use Policy.
• All audio files must comply with Canva's Terms of Use.

API reference

• addAudioTrack
• upload

Code sample

import React from "react";
import { addAudioTrack, AudioTrack } from "@canva/design";
import { upload } from "@canva/asset";

export function App() {
  async function handleClick() {
    // Upload an audio file
    const result = await upload({
      type: "audio",
      title: "Example audio",
      url: "https://www.canva.dev/example-assets/audio-import/audio.mp3",
      mimeType: "audio/mp3",
    });

    // Add the audio track to the design
    await addAudioTrack({
      ref: result.ref,
    });
  }

  return (
    <div>
      <button onClick={handleClick}>Add audio track to design</button>
    </div>
  );
}