dub-script

Easily dub audio files using a simple command script.

Usage

The example below mixes a voice file from a remote source with a background song.

import dubscript as ds

segment = ds.process({
  "version": "3",
  "audio": [{
      "type": "overlay",
      "audio": [
        {
            "name": "voice",
            "start": 500,
            "audio": [
                {"type": "file", "src": "https://mysite.com/1.wav"},
                {"type": "silence", "duration": 1000},
                {"type": "file", "src": "https://mysite.com/2.wav"},
            ]
        },
        {
            "name": "song",
            "audio": [
                {"type": "file", "src": "local/dir/bg.mp3", "gain": -10}
            ]
        }
      ]
  }]
})

segment.export('podcast.mp3')

Dependencies

dub-script is powered by Pydub and inherits its dependencies. Install ffmpeg or libav if you need to manipulate non-wave files, like mp3.

Installation

python setup.py install

Why?

This lib was originally intended to generate a podcast from a few audio files. You can use Pydub for this, but the idea of having a JSON recipe for it has several advantages. Having a recipe means you can version it and keep track of changes. Also, you can easily create a REST API that generates audios using dub-script. Finally, I find it easier to understand the audio processing when only looking at the JSON.

Commands

With dub-script, everything is done through commands that follow this basic structure:

{
  "type": "<command_type>"
}

The only exception is the concat command, which doesn't have a type:

{
  "audio": [
    // audios to concatenate here
  ]
}

Load local or remote files

Use file to load audio data.

{
  "type": "file",

  // you can have either an url or a path
  "src": "<local or remote source>"
}

Add silence

Use silence to add a silent bit in milliseconds.

{
  "type": "silence",
  "duration": 1000
}

Concatenate

Join audio together with concatenate:

{
  "audio": [
    { "type": "file1.wav" },
    { "type": "file2.wav" }
    // ...
  ]
}

Overlay

Mix audio tracks that plays at the same time with overlay.

Note: the length of the overlaid audio will always be equal to the first audio in the series.

{
  "type": "overlay",
  "audio": [
    // holds the tracks
    {
      "name": "track1", // track names are not required and are only here for organization purposes (yet)
      "start": 3000, // this track will be delayed by 3 seconds
      "audio": [{ "type": "file1.wav" }, { "type": "file2.wav" }]
    },
    {
      "audio": [{ "type": "file3.wav" }],
      "gain": 5 // the previous track will be boosted by +5 db while they overlap
    }
  ]
}

Filters

Filters can be applied to any other command.

Change volume

You can change the volume with gain. For instance:

{
  "type": "file",
  "src": "quiet.wav",
  "gain": 3
}

Fade In/Out

Fade audio with either fade_in or fade_out:

{
  "audio": [
    {
      "type": "file",
      "src": "intro.mp3",
      "fade_in": 3000 // fade the first 3 seconds
    },
    {
      "type": "file",
      "src": "main.mp3",
      "fade_out": 10000 // fade the last 10 seconds
    }
  ]
}

License

Licensed under the MIT License.