Creating audio tracks

How to add audio tracks to a user's design.

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 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:

NameMIME typeCommon file extensions
MPEGaudio/mpeg.mpg, .mpeg, .mp1, .mp2, .mp3
MP4 Audioaudio/mp4.mp4, .m4a
M4Aaudio/x-m4a.m4a
MP3audio/mp3.mp3
OGGaudio/ogg.ogg, .oga
WAVaudio/wav.wav
X-WAVaudio/x-wav.wav
WEBMaudio/webm.webm

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";
ts

Call the method, passing in the options shown here:

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

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);
ts

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";
ts

Call the method, passing in the options shown here:

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

The only required property is the ref property.

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",
id: "uniqueIdGoesHere",
title: "Example audio",
url: "https://www.canva.dev/example-assets/audio-import/audio.mp3",
mimeType: "audio/mp3",
durationMs: 86047,
});
// Add the audio track to the design
await addAudioTrack({
ref: result.ref,
});
}
return (
<div>
<button onClick={handleClick}>Add audio track to design</button>
</div>
);
}
tsx