Working with Audio

Audio layers function similarly to video layers but never appear visually on the canvas. They are entirely dedicated to the auditory mix.

Basic Audio Object

A basic audio layer requires an asset_id. time is required unless composition.auto_stitch is true. With auto-stitch, untimed audio in mixed timelines defaults to start_seconds: 0 and is aligned to the stitched video duration unless you set explicit time. If the requested duration is longer than the source audio, the audio will simply end early unless you enable looping.

{
  "id": "bg-music",
  "type": "audio",
  "asset_id": "asset-music-1",
  "time": {
    "start_seconds": 0,
    "duration_seconds": 15
  }
}

Auto-Stitch Audio

If composition.auto_stitch is enabled, you can omit time from audio layers. In mixed video+audio timelines, ReelForger will start untimed audio at 0 and align it to the stitched video length.

{
  "composition": {
    "auto_stitch": true,
    "timeline": [
      {
        "id": "intro-video",
        "type": "video",
        "asset_id": "asset-video-1"
      },
      {
        "id": "bed-track",
        "type": "audio",
        "asset_id": "asset-music-1"
      }
    ]
  }
}

Timeline order for layers does not append untimed audio after video; the bed still starts at 0 and spans the full stitched video duration. Use explicit time if the soundtrack should begin after a clip or end before the video does.

If you need audio to start later, end early, or run longer than the stitched video window, provide explicit time.start_seconds and time.duration_seconds.

Volume Control

You can control the mix of your audio layer using the volume property inside media_settings. Volume is a multiplier: 1.0 is original volume, 0.5 is 50% volume, and 0.0 is muted.

{
  "id": "voiceover",
  "type": "audio",
  "asset_id": "asset-vo-1",
  "media_settings": {
    "volume": 0.8
  }
}

Looping Audio

If you have a short music track (e.g., a 10-second loop) but your video composition is 300 seconds long, you can enable loop in the media_settings. The audio will repeat seamlessly until it reaches the layer's duration_seconds.

{
  "id": "looping-beat",
  "type": "audio",
  "asset_id": "asset-beat-1",
  "time": {
    "start_seconds": 0,
    "duration_seconds": 60
  },
  "media_settings": {
    "loop": true,
    "volume": 0.2
  }
}

Fades and Crossfades

You can explicitly add fade-in and fade-out animations to audio layers using fade_in_seconds and fade_out_seconds. ReelForger will automatically ramp the volume smoothly.

{
  "id": "fading-music",
  "type": "audio",
  "asset_id": "asset-music-1",
  "time": {
    "start_seconds": 0,
    "duration_seconds": 10
  },
  "media_settings": {
    "fade_in_seconds": 2.0,
    "fade_out_seconds": 3.0
  }
}

Trim vs Timeline Time

For audio/video layers, these two fields do different jobs:

• time.start_seconds: where the layer begins in the final composition
• trim.start_seconds: where playback begins inside the source media file

{
  "id": "music-from-chorus",
  "type": "audio",
  "asset_id": "asset-music-1",
  "time": {
    "start_seconds": 5,
    "duration_seconds": 12
  },
  "trim": {
    "start_seconds": 30
  }
}

In that example, the layer starts at 5s in the final video, but playback starts 30s into the source audio file.

Audio media settings

Available media_settings keys for audio layers:

The Full Audio Request Example

This example demonstrates how to add a quiet, looping background track to a 10-second composition.

curl -X POST https://api.reelforger.com/v1/videos/render \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "v1",
    "output": {
      "width": 1080,
      "height": 1920,
      "fps": 30
    },
    "assets": [
        {
          "id": "asset-music",
          "type": "audio",
          "url": "https://example.com/looping-beat.mp3"
        }
    ],
    "composition": {
        "timeline": [
          {
            "id": "bgm-layer",
            "type": "audio",
            "asset_id": "asset-music",
            "time": {
              "start_seconds": 0,
              "duration_seconds": 10
            },
            "media_settings": {
              "volume": 0.1,
              "loop": true,
              "fade_in_seconds": 1.0,
              "fade_out_seconds": 1.0
            }
          }
        ]
    }
  }'