Upload an episode
Prerequisites
Before continuing, you should have already read:
In this Guide
- Uploading an Episode
- Uploading an Episode with Metadata
- Uploading an Episode with Chapters
- Uploading an Episode Scheduled to be Published Later
- Supported Audio File Formats
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
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
Example: Uploading an episode with auto-sharing
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
Example: Upload an episode with chapters
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
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
Supported Audio File Formats
We support the following formats: MP3, MP4, WAV, 3GP, AAC, AMR, FLAC, OGG, RA, WMA, ASF.