Upload an episode

Prerequisites

Before continuing, you should have already read:

In this Guide

Uploading an Episode

To upload an episode, send a POST request to /v2/shows/SHOW-ID/episodes. The request must be authenticated, and you should replace SHOW-ID with the ID of the show where the episode should be placed. Spreaker requires that each episode belong to a show.

You can list your own shows using the Retrieving a User’s Shows API or you can create a new one using Creating a Show API.

Example: Upload an episode

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F media_file=@audio.mp3 -F "title=Daily News" https://api.spreaker.com/v2/shows/1/episodes

If successful, the response will contain the episode data (including the episode_id for future reference), and your episode will be immediately queued up for processing.

Processing can take anywhere from a few seconds to a few minutes, and will generate an MP3, stereo, 44.1Khz, CBR (Constant Bit-Rate) version of your audio file. Spreaker keeps both the original audio file and its re-encoded version, using the original whenever possible and only falling back to the re-encoded MP3 when the original file format is not supported by the player.

Uploading an Episode with Metadata

The API POST /v2/shows/SHOW-ID/episodes supports additional optional parameters that you can pass in order to add metadata to your episode and change the default settings:

Parameter Required Description
title yes Episode title
media_file yes Episode audio file
description no Episode description
tags no Comma-separated list of tags
explicit no If true the episode is flagged as explicit (defaults to false)
download_enabled no If false the episode will not be downloadable (defaults to true)
hidden no If true the episode will be private (defaults to false)
image_file no Episode image file
chapters no Episode chapters (see below)
autoshares no Enable auto-sharing to social networks. The value can be a comma separated list of values: FACEBOOK, TWITTER, TUMBLR, YOUTUBE (see example below).

Example: Uploading an episode with metadata

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F media_file=@audio.mp3 -F "title=Daily News" -F "description=Daily sport news" -F "tags=sport,news" -F "explicit=false" -F "download_enabled=true" -F "hidden=false" https://api.spreaker.com/v2/shows/1/episodes

Example: Uploading an episode with auto-sharing

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F media_file=@audio.mp3 -F "title=Daily News" -F "autoshares=FACEBOOK,TWITTER" https://api.spreaker.com/v2/shows/1/episodes

IMPORTANT: Please note that in order to get auto-sharing to work, you have to connect your social network accounts to Spreaker.

Uploading an Episode with Chapters

The API POST /v2/shows/SHOW-ID/episodes supports chapters, which allows you to pass a list of chapters displayed on Spreaker’s website.

The chapters parameter should be a JSON-encoded array of timecoded items, where each item should have the following properties:

Property Required Description
starts_at yes The position, in milliseconds, relative to the beginning of the audio file, at which the chapter begins
title yes The chapter’s title
external_url no An optional URL linking to a resource related to the chapter that provides extra information

Example: Schema

The following JSON describes an episode with two chapters:

  • The “Headline #1” chapter, starting at 00:30
  • The “Headline #2” chapter, starting at 02:00
[
    { "starts_at": "30000",  "title": "Headline #1" },
    { "starts_at": "120000", "title": "Headline #2", "external_url": "https://cnn.com" }
]

Example: Upload an episode with chapters

CHAPTERS=`echo '[
    { "starts_at": "30000",  "title": "Headline #1" },
    { "starts_at": "120000", "title": "Headline #2", "external_url": "https://cnn.com" }
]' | json -g`
curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F media_file=@audio.mp3 -F "title=Breaking News" -F "chapters=$CHAPTERS" https://api.spreaker.com/v2/shows/1/episodes

Episode Chapters also have the option of an added image per single chapter, but unfortunately images are not supported by the POST /v2/shows/SHOW-ID/episodes API. If you want to add images with each chapter, then please use the dedicated API: see Add a Chapter and Update a Chapter.

Uploading an Episode Scheduled to be Published Later

When you upload an episode it gets immediately published by default and will be public once server-side processing completes successfully. If this isn’t the desired behaviour, Spreaker gives you the option to upload an episode and schedule it to be published later.

To schedule the uploaded episode to be published later, you have to include the parameter auto_published_at in the request and set it to a future date/time. If set, the episode will not be immediately published, but will be published at the future date and time specified by auto_published_at (UTC timezone).

Example: Upload an episode scheduled to be published later

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F media_file=@audio.mp3 -F "title=Tomorrow News" -F "auto_published_at=2020-04-20 18:00:00" https://api.spreaker.com/v2/shows/1/episodes

Unscheduling an Episode Scheduled to be Published Later

If the episode is scheduled to be published later and the future date / time has not been reached yet, you can switch it back to the unscheduled state by invoking the episode editing API with the parameter auto_published_at set to an empty string.

Example: Unschedule an episode scheduled to be published later

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F "auto_published_at=" https://api.spreaker.com/v2/episodes/EPISODE-ID

Supported Audio File Formats

We support the following formats: MP3, MP4, WAV, 3GP, AAC, AMR, FLAC, OGG, RA, WMA, ASF.