home / skills / remotion-dev / remotion / add-sfx

add-sfx skill

safe

This skill helps you add a new sound effect to the Remotion SFX library by guiding integration from remotion.media and exporting for use.

npx playbooks add skill remotion-dev/remotion --skill add-sfx

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.4 KB

---
name: add-sfx
description: Add a new sound effect to @remotion/sfx
---

## Prerequisites

Sound effects must first be added to the [remotion.media](https://github.com/remotion-dev/remotion.media) repository. The source of truth is `generate.ts` in that repo. A sound effect must exist there before it can be added to `@remotion/sfx`.

Sound effects must be:
- WAV format
- CC0 (Creative Commons 0) licensed
- Normalized to peak at -3dB

## Steps

### 1. Add to `remotion.media` repo (must be done first)

In the `remotion-dev/remotion.media` repo:

1. Add the WAV file to the root of the repo
2. Add an entry to the `soundEffects` array in `generate.ts`:
   ```ts
   {
     fileName: "my-sound.wav",
     attribution:
       "Description by Author -- https://source-url -- License: Creative Commons 0",
   },
   ```
3. Run `bun generate.ts` to copy it to `files/` and regenerate `variants.json`
4. Deploy

### 2. Add the export to `packages/sfx/src/index.ts`

Use camelCase for the variable name. Avoid JavaScript reserved words (e.g. use `uiSwitch` not `switch`).

```ts
export const mySound = 'https://remotion.media/my-sound.wav';
```

### 3. Create a doc page at `packages/docs/docs/sfx/<name>.mdx`

Follow the pattern of existing pages (e.g. `whip.mdx`). Include:
- Frontmatter with `image`, `title` (camelCase export name), `crumb: '@remotion/sfx'`
- `<AvailableFrom>` tag with the next release version
- `<PlayButton>` import and usage
- Description
- Example code using `@remotion/media`'s `<Audio>` component
- Value section with the URL in a fenced code block
- Duration section (fetch the file and use `afinfo` on macOS to get duration/format)
- Attribution section with source link and license
- See also section linking to related sound effects

### 4. Register in sidebar and table of contents

- `packages/docs/sidebars.ts` — add `'sfx/<name>'` to the `@remotion/sfx` category items
- `packages/docs/docs/sfx/table-of-contents.tsx` — add a `<TOCItem>` with a `<PlayButton size={32}>`

### 5. Update the skills rule file

Add the new URL to the list in `packages/skills/skills/remotion/rules/sfx.md`.

### 6. Build

```bash
cd packages/sfx && bun run make
```

## Naming conventions

| File name | Export name |
|-----------|------------|
| `my-sound.wav` | `mySound` |
| `switch.wav` | `uiSwitch` (reserved word) |
| `page-turn.wav` | `pageTurn` |

## Version

Use the current version from `packages/core/src/version.ts`.
For docs `<AvailableFrom>`, increment the patch version by 1.

Overview

This skill adds a new sound effect to @remotion/sfx so it becomes available for programmatic video projects. It guides you through required prerequisites, how to add the audio asset and export, and the documentation and build steps needed to ship the sound effect. Follow the checklist to ensure consistent naming, licensing, and metadata.

How this skill works

The skill verifies that the WAV file exists in the remotion.media source-of-truth and then adds a public export URL to the @remotion/sfx package. It creates or updates documentation pages, sidebar entries, a table-of-contents entry with a playable preview, and the skills rules file. Finally, it builds the sfx package and increments the docs availability version where required.

When to use it

You have a CC0 WAV sound effect normalized to peak at -3dB ready for distribution.
You need the sound hosted in remotion.media before adding it to @remotion/sfx.
You want consistent docs and preview playback for new sfx assets.
You must register the asset in site navigation and the skills rules list.

Best practices

Add the WAV to remotion.media first; that repo is the single source of truth.
Use WAV format, CC0 license, and normalize peaks to -3dB before upload.
Name exports in camelCase and avoid JavaScript reserved words (e.g., use uiSwitch instead of switch).
Add a docs page with frontmatter, <AvailableFrom> incremented by one patch, a PlayButton, duration, attribution and example code.
Add the new item to the docs sidebar, sfx table of contents, and the skills rules list before building.
Use the current version from core version.ts when setting availability and build after all changes.

Example use cases

Add a UI click or ambient effect to programmatic video templates.
Provide a licensing-compliant library of SFX for community contributors.
Ship a new sfx asset with playback demo and usage snippet for creators.
Register a bulk of new sounds while keeping docs, navigation and build artifacts in sync.

FAQ

Where must the WAV file be added first?

Add the WAV to the remotion.media repository first; it is the source of truth and must be processed there before adding to @remotion/sfx.

What format and license are required?

WAV format only, Creative Commons 0 license, and audio normalized to peak at -3dB.

How should I name the export?

Use camelCase for the export name and avoid reserved words; transform names like page-turn.wav to pageTurn and switch.wav to uiSwitch.