Dynamic podcast ad insertion using the Edit API

Podcasts have gained popularity in recent times and it's not uncommon to monetise them by inserting audio ads. It is reasonably straight forward to edit an audio file and insert ads manually.

But what if you want to automate and scale the process. For example, you might want to dynamically insert different ads depending on the audience or when an advertiser uploads a new advert to a podcast management system. You might need to edit 1000's of audio files which would be too time consuming to do manually.

In this tutorial, we will show you how to do dynamic podcast ad insertion using the Shotstack Edit API and a JSON template. Follow these steps and you can set up your own podcast advertising workflows.

Pre-requisites

Here's what you will need to follow the steps outlined in the guide:

• A Shotstack API key. Sign up and get one for free.
• Basic knowledge of the curl utility and running commands in a terminal.

Using Shotstack as an audio editing API

Shotstack is a cloud-based video editing API that allows you to edit videos programmatically. But it can also be used as an audio editing API. You can sequence audio clips and render an mp3 file instead of a video.

Options like start, duration, trim and merge can be used to organise audio files on a timeline. There are also audio fade effects that can be applied to the audio clips.

When you send the JSON request to the Edit API, simply set the output format to mp3 instead of mp4. The API will return an mp3 file that you can listen to or download.

Insert ads into a podcast using the Edit API

The following is a walkthrough of using the Edit API to insert ads into a podcast audio. We'll begin by preparing a JSON template.

It will include an excerpt from a financial podcast saved as an mp3 file:

https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/audio/financial-podcast.mp3

We have also generated two podcast jingles using the amazing AI music generator Suno as the ads. Our ads are for two fictional companies, a London tailor and a premium vodka brand. You can listen to these below:

https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/audio/tailor-podcast-advert.mp3

https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/audio/vodka-podcast-advert.mp3

All the files are stored in our AWS S3 bucket but they can be anywhere online or uploaded using our Ingest API.

We'll insert these ads in to the podcast using a JSON template. Then, we'll send the template to the API, get the render ID, and use it to retrieve the final output.

Prepare the JSON podcast template

Create a podcast.json file with the JSON content below.

{
    "timeline": {
        "background": "#000000",
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "audio",
                            "src": "{{ PODCAST_AUDIO }}"
                        },
                        "start": 0,
                        "length": 25
                    },
                    {
                        "asset": {
                            "type": "audio",
                            "src": "{{ ADVERT_1 }}"
                        },
                        "start": "auto",
                        "length": "auto"
                    },
                    {
                        "asset": {
                            "type": "audio",
                            "src": "{{ PODCAST_AUDIO }}",
                            "trim": 25
                        },
                        "start": "auto",
                        "length": 25
                    },
                    {
                        "asset": {
                            "type": "audio",
                            "src": "{{ ADVERT_2 }}"
                        },
                        "start": "auto",
                        "length": "auto"
                    },
                    {
                        "asset": {
                            "type": "audio",
                            "src": "{{ PODCAST_AUDIO }}",
                            "trim": 50
                        },
                        "start": "auto",
                        "length": "auto"
                    }
                ]
            }
        ]
    },
    "output": {
        "format": "mp3",
        "size": {
            "width": 16,
            "height": 16
        }
    },
    "merge": [
        {
            "find": "PODCAST_AUDIO",
            "replace": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/audio/financial-podcast.mp3"
        },
        {
            "find": "ADVERT_1",
            "replace": "https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/audio/tailor-podcast-advert.mp3"
        },
        {
            "find": "ADVERT_2",
            "replace": "https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/audio/vodka-podcast-advert.mp3"
        }
    ]
}

The template includes placeholders and merge field data for our podcast audio file and the two adverts. Using this template you could easily swap the files and generate and unlimited number of variations. Simply replace the URLs in the merge array with your assets URLs.

In the example above, our podcast is 67 seconds long and the ads are about 20 seconds. For a real podcast you would want to adjust the trim and length values so that ads play less frequently.

For example, assuming your podcasts are usually 30 minutes long. And you want to include an advert after every 10 minutes. You can do so with a trim value of 600 (the value is calculated in seconds) for the portion of your podcast that plays after the first ad. And a value of 1200 for the part that plays after the second ad.

By setting the start to auto for all clips, we make them play in sequence one after another. We don't need to calculate it based on the duration of each file. We use the auto value for the length property to play the entire advert. You can also specify a duration in seconds if the ads are always going to be a fixed duration.

Post the template to the render endpoint

Run the following curl command to POST the template to the API render endpoint. Make sure to replace SHOTSTACK_API_KEY with your Shotstack API for the stage environment.

curl -X POST \
    -H "Content-Type: application/json" \
    -H "x-api-key: SHOTSTACK_API_KEY" \
    -d @podcast.json \
    https://api.shotstack.io/stage/render

You will get a JSON response back from the API which will contain a response.id value.

{
    "success": true,
    "message": "Created",
    "response": {
        "message": "Render Successfully Queued",
        "id": "879e7a4d-61f5-43c3-9619-ff67e3217974"
    }
} 

Copy the id from the response. We will use it to check the status of the render in the next step.

Get the render status of the audio file

The audio might take some time to render. Send a GET request to the API to check the status. Use the curl command below after replacing RENDER_ID with the id from the previous step, and SHOTSTACK_API_KEY with your API key.

curl -X GET \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    https://api.shotstack.io/stage/render/RENDER_ID

If the request is successful, you should see a response similar to this:

{
    "success": true,
    "message": "OK",
    "response": {
        "id": "879e7a4d-61f5-43c3-9619-ff67e3217974",
        "owner": "77buwktc5s",
        "plan": "basic",
        "status": "done",
        "error": "",
        "duration": 107,
        "billable": 107,
        "renderTime": 9433.74,
        "url": "https://shotstack-api-stage-output.s3-ap-southeast-2.amazonaws.com/77buwktc5s/879e7a4d-61f5-43c3-9619-ff67e3217974.mp3",
        "poster": null,
        "thumbnail": null,
        "created": "2024-04-15T07:49:55.035Z",
        "updated": "2024-04-15T07:50:05.674Z"
    }
}

Check the value of the response.status property. If it's done, it means the render is complete, and you can access the final audio via the value of the response.url property. Copy and paste the URL in your browser to listen to the final audio with the ads included or to download it.

If, however, the response.status parameter shows other values, like rendering or queued, wait for a few seconds and resend the same GET request.

Here is the final podcast audio file with the two ads stitched in to it:

Conclusion

In this guide, you have learned how to include ads in your podcast audio. We covered how to do this using a JSON template that is easy to customise. Using this guide as a starting point, you could build out a service that matches advertisers with podcast hosts and automatically insert the ads. What's more, you could add different ads to the same podcast to target specific audiences depending on variables like location, time of the day or local language.