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.

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⁠(opens in a new tab or window) 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.

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

The maximum size of an audio file is 50MB.

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.

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",
  aiDisclosure: "none"
});

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.

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.

• All audio files must comply with Canva's Acceptable Use Policy⁠(opens in a new tab or window).
• All audio files must comply with Canva's Terms of Use⁠(opens in a new tab or window).

• addAudioTrack
• upload

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",
      aiDisclosure: "none"
    });

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

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