JSON API: Details of Productions and Presets
The basic syntax for creating and changing productions and presets is very similar, only the URLs are different.
- Create a production/preset:
https://auphonic.com/api/{presets|productions}.json
This creates a new Production or Preset, where
{presets|productions}
should be either presets or productions.All details can be set in JSON format, see Set all Details in one Request for an example.
- Upload local files:
https://auphonic.com/api/{preset|production}/{uuid}/upload.json
Local file uploads must be handled in an additional request (encoded in
multipart/form-data
, not JSON). Set the fieldimage
to add a cover image and setinput_file
to upload an audio or video file (in productions only).- Start a production:
https://auphonic.com/api/production/{uuid}/start.json
This starts the audio post production of the Production with the given UUID.
You can also start a production by adding"action": "start"
as a parameter to the production create/change request (see example Upload Files with HTTP).
- Publish a production to Outgoing File Transfers:
https://auphonic.com/api/production/{uuid}/publish.json
Publishes the audio post production of the Production with the given UUID to all Outgoing File Transfers.
This will only take effect if the production contains Outgoing File Transfers andin_review
istrue
.- Change a production/preset:
https://auphonic.com/api/{preset|production}/{uuid}.json
Here
{uuid}
is the UUID of the preset/production you want to change. All sub-dictionaries can be changed in the same format as in the Set all Details in one Request example.
For the creation of multitrack productions and presets, see Multitrack Productions and Presets.
Create a Production with Detailed Audio Metadata
Audio Metadata can be set using the metadata
parameter:
curl -X POST -H "Content-Type: application/json" \
https://auphonic.com/api/productions.json \
-u username:password \
-d '{
"metadata": {
"title": "Production Title",
"artist": "The Artist",
"album": "Our Album",
"track": 1,
"subtitle": "Our subtitle",
"append_chapters": true,
"summary": "Our very long summary.",
"genre": "Podcast",
"year": 2012,
"publisher": "that's me",
"url": "https://auphonic.com",
"license": "Creative Commons Attribution 3.0 Austria",
"license_url": "http://creativecommons.org/licenses/by/3.0/at/",
"tags": ["podcast", "auphonic api", "metadata"],
"location": {
"latitude": "47.070",
"longitude": "15.439"
}
}
}'
Note
Metadata tags, chapters and cover images from input files are imported automatically if they are not set here!
Hint
Metadata fields can make use of Variables and Placeholders.
The response contains the UUID of the created production/preset:
{
"status_code": 200,
...
"data": {
...
"uuid": "KKw7AxpLrDBQKLVnQCBtCh",
...
}
}
Now let’s add an input file and a cover image to the newly created production:
curl -X POST https://auphonic.com/api/production/KKw7AxpLrDBQKLVnQCBtCh/upload.json \
-u username:password \
-F "input_file=@/home/user/your_audio_file.mp3" \
-F "image=@/home/user/your_cover_image.jpeg"
You may also add a cover image by just referencing a valid picture URL:
curl -X POST -H "Content-Type: application/json" https://auphonic.com/api/production/KKw7AxpLrDBQKLVnQCBtCh.json \
-u username:password \
-d '{"image": "https://auphonic.com/static/images/logo.png"}'
Output Files
Add Output Files to an existing production:
curl -H "Content-Type: application/json" -X POST \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{
"output_files": [
{"format":"mp3", "bitrate":"96"},
{"format":"aac", "bitrate":"64"},
{"format":"flac"}
]
}'
- The following Output Files are available (among others):
mp3
mp3-vbr
: MP3 with variable bitrate encodingvorbis
: Ogg Vorbisopus
: Opus Codecaac
(MP4/M4A)flac
alac
(MP4/M4A)wav
: uncompressed WAV 16-bit PCMwav-24bit
: uncompressed WAV 24-bit PCMvideo
: Video Output, format is the same as the input videoaudiogram
: Audiogram (Waveform Video) output fileinput
: unprocessed original input audio/video file, same format as inputdescr
: Production Description in xml/json/yamlstats
: Audio Processing Statistics in txt/json/yamlchaps
: Chapter Marks as txt file (as used by mp4chaps)psc
: Chapter Marks in Podlove Simple Chapters formatcut-list
: Filler and Silence Cuts in a list formatimage
: a copy of the Cover Imagewaveform
: Waveform Image of output audio filewavedat
: Waveform Data File
To query all available formats, bitrates and filename endings, use the following request:
curl https://auphonic.com/api/info/output_files.json
which returns:
{
"status_code": 200,
...
"data": {
"mp3": {
"type": "lossy",
"bitrates": ["32", "40", "48", ... ],
"bitrate_strings": ["32 kbps (~14MB/h)", "40 kbps (~18MB/h)" , ...],
"display_name": "MP3",
"default_bitrate": "96",
"endings": ["mp3"]
},
"opus": {
"type": "lossy",
"bitrates": ["6", "12", "16", ...],
"bitrate_strings": ["~6 kbps (~3MB/h)", "~12 kbps (~5MB/h)", ...],
"display_name": "Opus",
"default_bitrate": "48",
"endings": ["opus"],
},
"aac": {
"type": "lossy",
"bitrates": ["24", "32", "40", "48", ... ],
"bitrate_strings": ["24 kbps, HE AAC (~11MB/h)", "32 kbps, HE AAC (~14MB/h)", ...],
"display_name": "AAC (M4A, MP4, M4B)",
"default_bitrate": "64",
"endings": ["mp4", "m4a", "m4b"]
},
"vorbis": {
"type": "lossy",
"bitrates": ["32", "40", "48", ... ],
"bitrate_strings": ["~32 kbps (~14MB/h)", "~40 kbps (~18MB/h)" , ...],
"display_name": "Ogg Vorbis",
"default_bitrate": "80",
"endings": ["ogg", "oga"]
},
"flac": {
"type": "lossless",
"bitrate_strings": ["optimal (stereo ~125MB/h, mono ~62MB/h)"],
"display_name": "FLAC",
"endings": ["flac"]
},
"alac": {
"type": "lossless",
"bitrate_strings": ["optimal (stereo ~130MB/h, mono ~65MB/h)"],
"display_name": "ALAC (M4A, MP4)",
"endings": ["mp4", "m4a"]
},
"mp3-vbr": {
"type": "lossy",
"bitrates": ["32", "40", "48", ... ],
"bitrate_strings": ["~32 kbps (~14MB/h)", "~40 kbps (~18MB/h)" , ...],
"display_name": "MP3 Variable Bitrate",
"default_bitrate": "96",
"endings": ["mp3"]
}
"wav": {
"type": "lossless",
"bitrate_strings": ["optimal (stereo ~635MB/h, mono ~318MB/h)"],
"display_name": "WAV 16-bit PCM",
"endings": ["wav"]
}
"video": {
"display_name": "Video (same format as input)",
"bitrate_strings": ["same bitrate as input"],
"type": "video"
},
"chaps": {
"type": "description",
"display_name": "Chapters File",
"endings": ["chapters.txt"]
},
"psc": {
"type": "description",
"display_name": "Podlove Simple Chapters",
"endings": ["psc", "xml"]
},
"image": {
"type": "description",
"display_name": "Cover Image"
},
"stats": {
"display_name": "Audio Processing Statistics",
"type": "description",
"endings": ["txt", "json", "yaml"]
},
...
}
}
If no bitrate is specified in lossy audio formats, the default_bitrate
is taken -
type
can be lossy for lossy audio files, lossless for lossless
audio files, video for video output files and description for data
about a production.
If you want to create a Mono Mixdown or use the Split On Chapters feature, set a flag in JSON:
[
{"format": "mp3", "bitrate": "96"},
{"format": "wav", "mono_mixdown": true},
{"format": "vorbis","bitrate": "64", "split_on_chapters": true, "mono_mixdown": true},
{"format": "video", "mono_mixdown": true}
]
For further details, please see Output Files.
Setting Filenames
It’s possible to control how output filenames are constructed:
{"format":"mp3", "bitrate":"48", "filename":"MyFilename.mp3", "mono_mixdown":true}
Directly generates the file MyFilename.mp3. Must have a correct ending!
{"format":"aac", "bitrate":"64", "ending":"mp4"}
This will take the input file basename and adds mp4 as ending, e.g. original-filename.mp4.
{"format":"aac", "bitrate":"32", "suffix":"-small", "ending":"m4a"}
Takes the input file basename and adds suffix and ending, e.g. original-filename-small.m4a.
A filename in auphonic consists of an output_basename
, suffix
and an
ending
. The output basename can be set using the URL
https://auphonic.com/api/productions.json
or
https://auphonic.com/api/production/{uuid}.json
:
curl -X POST -H "Content-Type: application/json" https://auphonic.com/api/productions.json \
-u username:password \
-d '{
...
"output_basename": "production-filename",
"output_files": [
{"format":"aac", "bitrate":"32", "suffix":"-small", "ending":"m4a"}
{"format":"aac", "bitrate":"128", "ending":"m4a"}
]
...
}'
This will create the output files production-filename-small.m4a
and
production-filename.m4a
.
It’s also possible to set the full output filename for an output format. The full filename has priority over the single components like suffix, basename, etc.:
curl -X POST -H "Content-Type: application/json" \
https://auphonic.com/api/production/KKw7AxpLrDBQKLVnQCBtCh.json \
-u username:password \
-d '{
...
"output_basename": "production-filename",
"output_files": [
{"format":"mp3", "bitrate":"48", "filename":"MyFilename1.mp3", "suffix": "-small"}
{"format":"aac", "bitrate":"96", "filename":"MyFilename2.mp4", "ending": "m4a"}
]
...
}'
This will create the output files MyFilename1.mp3
and MyFilename2.mp4
.
Cut Lists
With the Cut Fillers and the Cut Silence algorithms you can automatically cut your audio file. Depending on whether you activate any cutting algorithm you can export the cuts in list form. This allows you to check if the cuts work for you.
See Export Cut Lists for more details and all available cut list formats.
In the API, you can select a specific cut list format using the ending
field.
In this example, we select Reaper regions and the DaVinci Resolve CMX3600 EDL format as the output formats:
-d '{
...
"output_files": [
{"format": "cut-list", "ending": "ReaperRegions.csv"},
{"format": "cut-list", "ending": "DaVinciResolve.edl"}
]
...
}'
Outgoing File Transfers
Similar to Upload Files with External Services (SFTP/FTP/Dropbox/etc.), External Services can be referenced for outgoing file transfers:
curl -H "Content-Type: application/json" -X POST \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{
"outgoing_services": [
{"uuid": "{service1_uuid}"}, {"uuid": "{service2_uuid}"}, ...
],
"review_before_publishing": false
}'
where {service1_uuid}
, {service2_uuid}
, etc. is the UUID of
the external service you want to add for outgoing file transfers.
review_before_publishing
: true or false (Default: false) - Require a review before publishing results to services.If you set
review_before_publishing
totrue
and there are any definedoutgoing_services
, this will setin_review
totrue
. After the production is done, you are able to Publish the production to Outgoing File Transfers if you are satisfied with the results.
For some outgoing file transfer services, additional parameters are available:
- Captivate:
draft
: true or false (Default: false)type
: “normal”, “trailer” or “bonus” – episode type as documented by Apple
- Facebook:
distribution
: everywhere (Post to News Feed: exported video is posted directly to your timeline), no_story (Exclude from News Feed: not posted to your timeline, but visible in the videos tab) or secret (only you can see the video)embeddable
: true or false
- PodBean:
draft
: true or falsetype
: “public”, “premium” or “private” – not all of these are allowed for every Podcast and the exact set allowed values depends on your subscription model and settings on PodBean
Note: There is currently no way to query the exact set of allowed values using the Auphonic API, please contact support if this is something you need!
- SoundCloud:
downloadable
: true or falsesharing
: public or privatetrack_type
: as returned by Query Service Types (same values as documented in the SoundCloud API Reference)
- Spreaker:
downloadable
: true or falsesharing
: public or privateshow
: one of your available shows on Spreaker, as returned by Query Service Types
- YouTube:
privacy
: public or privatecategory
: YouTube category, as returned by Query Service Types
For example, an outgoing file transfer to SoundCloud:
curl -H "Content-Type: application/json" -X POST \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{
"outgoing_services": [
{"uuid": "gxr975w3MzRS9ywnWsu6tL", "downloadable": true, "sharing": "public", "track_type": "podcast"}
]
}'
They support the same values as documented in the SoundCloud API Reference.
It’s also possible to query all registered External Services of a user:
curl https://auphonic.com/api/services.json -u username:password
which returns:
{
"status_code": 200,
...
"data": [
{
"display_name": "Georg Holzmann",
"type": "dropbox",
"uuid": "UC6aoChNZNt7KYZNxJTgUn",
"email": "georg@myserver.at",
"incoming": true,
"outgoing": true
},
{
"display_name": "my soundcloud account",
"type": "soundcloud",
"uuid": "Asu5PxueRRxtqfZhe7zdia",
"incoming": true,
"outgoing": true
},
{
"display_name": "my youtube vids",
"type": "youtube",
"uuid": "esSfxaPe6U2bNX2K9GGMeT",
"incoming": false,
"outgoing": true
},
{
"display_name": "Auphonic Spreaker Account",
"type": "spreaker",
"uuid": "UL7MZvjR3tntbCvbxu5Jsi",
"outgoing": true,
"incoming": true
},
{
"display_name": "my ftp server",
"path": "mirror/",
"host": "ftp.myserver.at",
"type": "ftp",
"uuid": "r6MSycBwyeWFAJYqUKtGeX",
"port": 21,
"base_url": "",
"permissions": "",
"incoming": true,
"outgoing": true
},
{
"display_name": "myserver.at SFTP"
"path": "/home/user/path",
"host": "myserver.at",
"type": "sftp",
"uuid": "jm7yLuiyGwQe27gQUz869K",
"port": 22,
"base_url": "http://myserver.at/audiofiles/",
"permissions": "664",
"incoming": true,
"outgoing": true
},
{
"outgoing": true,
"display_name": "mypodcast /quickcast",
"uuid": "h9KHD96Mks5JyfFuXYPXHk",
"libsyn_show_slug": "mypodcast",
"base_url": "http://traffic.libsyn.com/mypodcast/",
"port": 21,
"host": "ftp-server.libsyn.com",
"path": "/mypodcast/quickcast",
"incoming": false,
"type": "libsyn",
"libsyn_directory": "quickcast"
},
{
"outgoing": true,
"display_name": "auphonic bucket 1",
"uuid": "gRNT7i5NVxPiGCG8TmhpgF",
"type": "amazons3",
"bucket": "auphonic1",
"incoming": true,
"canned_acl": "public-read",
"key_prefix": "my-podcast/"
},
{
"type": "archiveorg",
"outgoing": true,
"display_name": "archive",
"uuid": "PQaZpL58TqvK9NvDnHu5Hj",
"incoming": false
},
{
"outgoing": true,
"display_name": "My WebDAV Server",
"uuid": "9k27BXTmvsKCdeoyXkHjVB",
"url": "https://mywebdav.com/myfiles/",
"base_url": "http://files.mywebdav.com/myfiles/",
"incoming": true,
"type": "webdav"
},
{
"outgoing": true,
"display_name": "Auphonic Blubrry Account",
"uuid": "xJTES9PCAu3uvLE3gwSjAN",
"program_keyword": "auphonic_blubrry_account",
"base_url": "http://content.blubrry.com/auphonic_blubrry_account",
"incoming": false,
"type": "blubrry"
},
{
"uuid": "mggo5JuLNLhVBkSpEA4tsg",
"display_name": "Auphonic PodBean Account",
"type": "oauthhoster.podbean",
"incoming": false,
"outgoing": true,
"podcast": {
"id": "JYJGk5T2gI3G",
"title": "Auphonic Podcast",
"url": "https://yourpodcast.podbean.com",
"image": [
{
"url": "https://djrpnl90t7dii.cloudfront.net/podbean-logo/podcast_standard_logo_v2.png"
}
],
"description": "Podcast Description"
}
}
]
}
The response contains different datasets for each external service,
but each service will have a type
and a uuid
.
incoming
and outgoing
indicates, if the service can be used for
incoming and/or outgoing file transfers.
All possible external service types on auphonic.com and their parameters can be queried with:
curl https://auphonic.com/api/info/service_types.json -u username:password
which returns:
{
"status_code": 200,
...
"data": {
"youtube": {
"display_name": "YouTube",
"parameters": {
"category": {
"default_value": "",
"type": "select",
"display_name": "Category",
"options": [
{
"display_name": "Autos & Vehicles",
"value": "Autos"
},
...
]
},
...
}
},
"soundcloud": {
"display_name": "SoundCloud",
"parameters": {
"downloadable": {
"default_value": true,
"type": "checkbox",
"display_name": "Downloadable"
},
...
}
},
"dropbox": {
"display_name": "Dropbox",
"parameters": null
},
...
}
}
The response also includes all available parameter values for each outgoing file transfer service! Please note that the range of accepted select values might be not include all the options returned by this API if it varies per-account for the service in question – this is true for the type
parameter of PodBean for instance.
Reference Output Files for Outgoing File Transfers
If you want to export a specific output file to an outgoing external service, you can reference the external service account while setting the output file details:
curl -H "Content-Type: application/json" -X POST \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{
"output_files": [
{"format":"mp3", "outgoing_services": ["uO7yLuiyGwQe27gQUz869K"]}
]
}'
which means that the mp3 output file will be copied to the outgoing external
service with the UUID
uO7yLuiyGwQe27gQUz869K.
If this service was not added as an outgoing file transfer to the current
production, then these settings will be ignored.
If you don’t use the outgoing_services
parameter in your output files,
then the optimal set of output files will be created automatically:
all files are copied to FTP, SFTP, Dropbox, WebDAV, AmazonS3, Archive.org and blubrry accounts
the lossy audio file with the highest bitrate is exported to a SoundCloud account
for YouTube outgoing file transfers, the video output is selected, or otherwise a video will be generated from your audio file with optimal quality settings
an MP3 output file will be generated for libsyn and Captivate outgoing file transfers
an MP3 output file will be generated for PodBean outgoing file transfers if no MP3 (including the VBR variant) or AAC file has been generated
Audio Algorithms
Setting Audio Algorithms parameters for a basic example:
curl -H "Content-Type: application/json" -X POST \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{
"algorithms": {
"leveler": true, "normloudness": true, "loudnesstarget": -23,
"filtering": true, "denoise": false, "denoiseamount": 0
}
}'
Note
A denoiseamount of 0 (default value) means automatic denoiseamount estimation!
This works exactly as in the production/preset form!
More Settings for Audio Algorithms
You can set all Audio Algorithm Parameters using the API (see list of all options below), as you can see in the following advanced example:
curl -H "Content-Type: application/json" -X POST \ https://auphonic.com/api/production/{uuid}.json \ -u username:password \ -d '{ "algorithms": { "leveler": true, "levelerstrength": 80, "compressor_speech": "medium", "compressor_music": "off", "musicgain": 3, "msclassifier": "on", "maxlra": 8, "maxs": 5, "maxm": 10, "denoise": true, "denoiseamount": 6, "dehum": 50, "dehumamount": 12, "normloudness": true, "loudnesstarget": -24, "maxpeak": -2, "dualmono": false, "loudnessmethod": "dialog", "silence_cutter": true, "filler_cutter": true, "cut_mode": "apply_cuts", } }'
- Options for Adaptive Leveler :
levelerstrength
: 100 (default), 90, 80, 70, … 0 (values in %)compressor
: auto (default), soft, medium, hard or off- Separate MusicSpeech Parameters Mode :
it is also possible to use separate levelerstrength and compressor parameters for speech and music segments
msclassifier
(use classifier or set everything to speech/music): on (default), speech, musiclevelerstrength_speech
,levelerstrength_music
: 100 (default), 90, 80, 70, … 0 (values in %)compressor_speech
,compressor_music
: auto (default), soft, medium, hard or offmusicgain
(add gain to music segments): -6, …, -1, 0 (default), 1, 2, …, 6 (values in dB)
- Broadcast Mode :
use a Maximum Loudness Range (LRA), Maximum Short-term Loudness or Maximum Momentary Loudness target to control the strength of the Leveler
maxlra
: 0 (Auto, default), 3, 4, 5, 6, …, 20 (values in LU)maxs
: 0 (Auto, default), 3, 4, 5, 6, …, 12 (values in LU, relative to the target loudness)maxm
: 0 (Auto, default), 8, 9, 10, 11, …, 20 (values in LU, relative to the target loudness)musicgain
(add gain to music segments): -6, …, -1, 0 (default), 1, 2, …, 6 (values in dB)
for details please see Adaptive Leveler Settings
- Options for Noise Reduction :
denoisemethod
: static (default), dynamic, speech_isolationdenoiseamount
(noise reduction amount): 0 (Auto, default), -1 (Off), 3, 6, … (values in dB)deverbamount
(requiresdenoisemethod
dynamic or speech_isolation): 0 (Auto, default), -1 (Off), 3, 6, … (values in dB)debreathamount
(requiresdenoisemethod
dynamic or speech_isolation): -1 (Off, default), 3, 6, … (values in dB)- Static Denoising:
denoiseamount
(noise reduction amount): 0 (Auto, default), -1 (disable denoise, dehum only), 3, 6, … (values in dB)dehum
(hum reduction base frequency): 0 (Auto, default), 50 or 60dehumamount
(hum reduction amount): 0 (Auto, default), -1 (disable dehum), 3, 6, … (values in dB)
- Options for Loudness Normalization :
maxpeak
(maximum true peak level): 0 (Auto, default), -0.5, -1, -1.5, -2, -3, -4, -5, -6 (values in dBTP)dualmono
(treat mono production as dual-mono / -3LU offset): false (default), trueloudnessmethod
(anchor-based loudness normalization): program (default), dialog (measure dialog/voice loudness)
- Options for Filtering:
filtering
: true (default), falsefiltermethod
: hipfilter (default), autoeq
- Options for Automatic cutting:
silence_cutter
: false (default), truefiller_cutter
: false (default), truecut_mode
(what happens to cut segments): apply_cuts (default), export_uncut_audio, set_cuts_to_silence
Please see Query Audio Algorithms and Parameters for details about all available options!
Query Audio Algorithms and Parameters
Audio Algorithms and all its available parameter values can be queried by:
curl https://auphonic.com/api/info/algorithms.json
which returns:
{
"status_code": 200,
"form_errors": {},
"error_code": null,
"error_message": "",
"data": {
"filtering": {
"default_value": true,
"type": "checkbox",
"display_name": "Filtering",
"description": "Filters unnecessary and disturbing low frequencies depending on the context (speech, music, noise)."
},
"normloudness": {
"default_value": true,
"type": "checkbox",
"display_name": "Global Loudness Normalization",
"description": "Adjusts the global, overall loudness to the specified Loudness Target, so that all processed files have a similar average loudness."
},
"loudnesstarget": {
"default_value": -18,
"type": "select",
"display_name": "Loudness Target",
"belongs_to": "normloudness",
"options": [
{
"display_name": "-13 LUFS (very loud)",
"value": -13
},
...
{
"display_name": "-24 LUFS, ATSC A/85 (TV, US)",
"value": -24
},
{
"display_name": "-31 LUFS (very dynamic audio, quiet)",
"value": -31
}
]
},
"denoise": {
"default_value": false,
"type": "checkbox",
"display_name": "Noise Reduction ",
"description": "Classifies regions with different background noises and automatically removes noise and hum."
},
"denoiseamount": {
"default_value": 0,
"type": "select",
"display_name": "Noise Reduction Amount",
"belongs_to": "denoise",
"options": [
{
"display_name": ""Automatic",
"value": 0
},
...
{
"display_name": ""6 dB (low)",
"value": 6
},
...
{
"display_name": "12 dB (medium)",
"value": 12
},
...
{
"display_name": "100 dB (complete)",
"value": 100
}
]
},
"leveler": {
"default_value": true,
"type": "checkbox",
"display_name": "Adaptive Leveler ",
"description": "Corrects level differences between speakers, music and speech, etc. to achieve a balanced overall loudness."
},
...
}
}
Adding Intro and Outro
You can automatically add an Intro and Outro to your main input file. Audio and video intros and outros are supported, with video intros and outros being limited to a length of 1 minute.
Intros and outros for presets always need External Services and can’t be uploaded directly, because we store your audio files only for a limited number of days. They are referenced in the same way as the main input file would be referenced (see Files form External Servers), using a service UUID and a filename.
The easiest way to add intros or outros to your existing production is to upload the files (this only works with productions, use External Services with Preset):
curl -X POST https://auphonic.com/api/production/{uuid}/upload.json \
-u username:password \
-F "intro_file=@/home/user/your_audio_intro_file.mp3"
-F "outro_file=@/home/user/your_audio_outro_file.mp3"
Note that this will always create (or replace) a single intro/outro.
The following command adds an intro from an external service to an existing production/preset:
curl -X POST -H "Content-Type: application/json" \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{
"multi_input_files": [
{
"service": "pmefeNCzkyT4TbRbDmoCDf",
"input_file": "my_dropbox_file.mp3",
"type": "intro"
}
]
}'
If you use HTTP as incoming service, just set the URI as input_file
and
omit the service
field:
curl -X POST -H "Content-Type: application/json" \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{
"multi_input_files": [
{
"input_file": "http://your_server.com/outro.mp3",
"type": "outro"
}
]
}'
It’s of course also possible to add intro and outro at once:
curl -X POST -H "Content-Type: application/json" \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{
"multi_input_files": [
{
"service": "qwsalxnVdasAOpsjeNsjQo",
"input_file": "my_sftp_intro.mp4",
"type": "intro"
},
{
"service": "pmefeNCzkyT4TbRbDmoCDf",
"input_file": "another_dropbox_file.mp3",
"type": "outro"
}
]
}'
Add multiple Intros or Outros
Using the same interface as in our Multitrack Productions, it is possible to add multiple intros/outros to a production as well. These intros/outros are played in series.
Every single call to multi_input_files
will append another intro/outro to your production.
Use the following to add two intros from an external service:
curl -X POST -H "Content-Type: application/json" \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{
"multi_input_files": [
{
"service": "qwsalxnVdasAOpsjeNsjQo",
"input_file": "my_sftp_intro_1.wav",
"type": "intro"
},
{
"service": "qwsalxnVdasAOpsjeNsjQo",
"input_file": "my_sftp_intro_2.wav",
"type": "intro"
}
]
}'
If you want to upload intros/outros directly (without an external service), each intro/outro needs an ID which is used to upload the audio file in a second request:
curl -X POST -H "Content-Type: application/json" \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{
"multi_input_files": [
{
"type": "intro",
"id": "first intro"
},
{
"type": "intro",
"id": "second intro"
}
]
}'
This will create empty intros. Now upload files using the IDs from above in a second request:
curl -X POST https://auphonic.com/api/production/{uuid}/upload.json \
-u username:password \
-F "first intro=@/home/user/your_first_audio_intro_file.mp3" \
-F "second intro=@/home/user/your_second_audio_intro_file.mp3"
If you want to delete all current intros/outros, use the following DELETE request:
curl -X DELETE https://auphonic.com/api/production/{uuid}/multi_input_files.json -u username:password
Overlapping Intros/Outros (Intro/Outro Offsets)
When creating intros/outros, it is possible to let them overlap with the main audio file or the next/previous intro/outro (using the same interface as in Multitrack Offsets).
For example, set the offset
parameter to 2 (in seconds), to let the intro overlap for 2 seconds with the next audio file:
curl -X POST -H "Content-Type: application/json" \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{
"multi_input_files": [
{
"service": "qwsalxnVdasAOpsjeNsjQo",
"input_file": "my_sftp_intro_1.wav",
"type": "intro",
"offset": 2
}
]
}'
Overlap for outros work the other way around: if an outro has an offset of 5 seconds, it will overlap 5 seconds with the previous audio file.
Audio Manipulations
We also offer some audio manipulation operations, they are API-only and cannot be controlled in our web interface.
Add Audio Insert Files
Audio Inserts are audio files, which will be inserted into your main audio file (singletrack or multitrack) at your defined offsets in seconds.
This can be used for Dynamic Ad Insertion by podcast hosting companies
(they will insert short audio ads at specific positions in a podcast audio file),
or if you want to construct an audio production out of multiple segments.
Audio inserts should be edited/processed already before using them in a production (like ads usually are). In an Auphonic production, they are only loudness normalized to match the loudness of your production without further Auphonic processing (no leveling, noise reduction, etc.).
Using the same interface as in Adding multiple Intros/Outros,
you can add audio insert files with a call to multi_input_files
.
Here is an example with one audio insert from an external service, another one from an https URL.
The offset/position in the main audio file must be given in seconds:
curl -X POST -H "Content-Type: application/json" \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{
"multi_input_files": [
{
"service": "qwsalxnVdasAOpsjeNsjQo",
"input_file": "my_sftp_insert_1.wav",
"type": "insert",
"offset": 20.5
},
{
"input_file": "https://mydomain.com/my_sftp_intro_2.wav",
"type": "insert",
"offset": 120.3,
}
]
}'
If you want to upload insert files directly (without an external service), each insert needs an ID which is used to upload the audio file in a second request:
curl -X POST -H "Content-Type: application/json" \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{
"multi_input_files": [
{
"type": "insert",
"id": "first ad",
"offset": 20.5
},
{
"type": "insert",
"id": "second ad",
"offset": 120.3,
}
]
}'
This will create empty audio inserts. Now upload files using the IDs from above in a second request:
curl -X POST https://auphonic.com/api/production/{uuid}/upload.json \
-u username:password \
-F "first ad=@/home/user/your_first_audio_file.mp3" \
-F "second ad=@/home/user/your_second_audio_file.mp3"
Cut Start/End of Audio Files
In singletrack productions, it is possible to cut the start and/or end of the uploaded audio file. All timing information (chapters, etc.) will be shifted accordingly.
To cut from the start of an audiofile, set the parameter cut_start
(in seconds)
when creating a production. To cut from the end, please use the parameter cut_stop
(calculated in seconds from the end of the audio file):
curl -X POST -H "Content-Type: application/json" \
https://auphonic.com/api/productions.json \
-u username:password \
-d '{
"cut_start": 2.34,
"cut_end": 5.142,
"metadata": { "title": "Cut the audio file!" }
}'
You can use the same parameters when modifying an existing production:
curl -X POST -H "Content-Type: application/json" \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{"cut_start": 2.34, "cut_end": 5.142}'
Fade In/Out Time of Audio Files
With our API, you can set the fade in/out time in ms at the start/end of output files. The default fade time is 100ms, values between 0ms and 5000ms are allowed.
To set a manual fade in/out time, please use the parameter fadetime
in our audio algorithms settings:
curl -H "Content-Type: application/json" -X POST \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{
"algorithms": {
"leveler": true, "normloudness": true, "filtering": true,
"fadetime": 0
}
}'
It is of course also possible to Set all Details in one Request:
curl -X POST -H "Content-Type: application/json" \
https://auphonic.com/api/productions.json \
-u username:password \
-d '{
"input_file": "http://your_server.com/somefile.mp3",
"algorithms": {
"filtering": true, "leveler": true, "normloudness": true,
"fadetime": 250
},
"metadata": {
"title": "Production with custom fade in/out",
},
"output_files": [
{"format":"aac", "bitrate":"32", "suffix":"-small"},
{"format": "flac"}
]
}'
Adding Speech Recognition
External Speech Recognition Services
First you have to register a speech recognition service at the External Services Page. For more information about speech recognition, please see Automatic Speech Recognition, Shownotes and Chapters.
Request to add a speech recognition service to a production (or preset):
curl -X POST -H "Content-Type: application/json" \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{
"speech_recognition": {"uuid": "{service_uuid}"}
}'
Depending on the speech recognition service, additional parameters must or can be added to the request.
If you use the Google Cloud Speech API, Amazon Transcribe or Speechmatics, the paramters keywords
and language
are available (you will get a list of all supported languages of your selected speech service in an API error message):
curl -X POST -H "Content-Type: application/json" \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{
"speech_recognition": {
"uuid": "6m8onAcvWHmZuJtDN6mzK8",
"keywords": ["keyword1", "keyword2", "A longer phrase"],
"language": "en-US"
}
}'
Auphonic Whisper Speech Recognition Service
Note
Restricted to paying users!
To use the Auphonic Whisper Speech Recognition Service, simply provide your desired language - and keywords, if necessary - but leave out the uuid field:
curl -X POST -H "Content-Type: application/json" \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{
"speech_recognition": {
"language": "en",
"keywords": ["keyword1", "keyword2", "A longer phrase"],
}
}'
Automatic Shownotes and Chapters
Note
Restricted to paying users!
To get autogenerated shownotes and chapters, just add the line "shownotes": true
in section speech recognition.
Additionally you may use "shownotes_summary_example": "..."
to provide a summary example.
curl -X POST -H "Content-Type: application/json" \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{
"speech_recognition": {
"language": "en",
"keywords": ["keyword1", "keyword2", "A longer phrase"],
"shownotes": true,
"shownotes_summary_example": "This is an example summary."
}
}'
All generated data will automatically show up once in your transcript html
or txt
file, once in the output files’ metadata (if you have not entered content before) and also in the API production details.
Generated chapters will appear just like manually added chapters, and generated shownotes are displayed in your production data as follows:
"shownotes": {
"summaries": {
"long": ["Example long summary."],
"brief": ["Example brief summary."],
"subtitle": ["Example subtitle summary."]
},
"tags": ["example_tag1","example_tag2","example_tag3"]
}
Output Formats
The Auphonic speech recognition API supports three types of output formats:
subtitle
: a subtitle format, available assrt
orwebvtt
speech
: a machine readable format, available asjson
orxml
transcript
a pure text format readable by humans, available ashtml
ortxt
Adding speech recognition to your production will always add the necessary output files as well. If you want different output formats, use the following request:
curl -H "Content-Type: application/json" -X POST \
https://auphonic.com/api/production/{uuid}.json \
-u username:password \
-d '{
"output_files": [{"format":"speech", "ending":"xml"}]
}'
Set all Details in one Request
It’s also possible to set all discussed details directly in one request:
curl -X POST -H "Content-Type: application/json" \
https://auphonic.com/api/productions.json \
-u username:password \
-d '{
"metadata": {
"title": "Production Title",
"artist": "The Artist",
"album": "Our Album",
"track": 1,
"subtitle": "Our subtitle",
"append_chapters": true,
"summary": "Our very long summary.",
"genre": "Podcast",
"year": 2012,
"publisher": "that's me",
"url": "https://auphonic.com",
"license": "Creative Commons Attribution 3.0 Austria",
"license_url": "http://creativecommons.org/licenses/by/3.0/at/",
"tags": ["podcast", "auphonic api", "metadata"],
"location": {
"latitude": "47.070",
"longitude": "15.439"
}
},
"output_basename": "production-filename",
"output_files": [
{"format": "mp3", "bitrate": "96", "mono_mixdown": true},
{"format":"aac", "bitrate":"32", "suffix":"-small", "ending":"m4a"},
{"format": "flac", "split_on_chapters": true}
],
"outgoing_services": [{"uuid": "UC6aoChNZNt7KYZNxJTgUn"}, {"uuid": "jm7yLuiyGwQe27gQUz869K"}],
"review_before_publishing": false,
"algorithms": {
"filtering": true, "leveler": true,
"normloudness": true, "denoise": true,
"loudnesstarget": -23, "denoiseamount": 12
},
"chapters": [
{"start": "00:00:00", "title": "Start Chapter", "url": "http://auphonic.com"},
{"start": "00:02:18", "title": "Second Chapter"},
{"start": "00:05:41", "title": "Final Chapter"}
],
"input_file": "http://your_server.com/somefile.mp3",
"multi_input_files": [
{
"input_file": "http://your_server.com/intro.mp3",
"type": "intro",
"offset": 2.3
},
{
"service": "pmefeNCzkyT4TbRbDmoCDf",
"input_file": "dropbox_outro_file.mp3",
"type": "outro"
}
],
"speech_recognition": {
"uuid": "6m8onAcvWHmZuJtDN6mzK8",
"keywords": ["Auphonic", "Holzmann", "Rattinger"],
"language": "de-DE",
"shownotes": true,
"shownotes_summary_example": "This is an example summary."
},
"image": "https://auphonic.com/static/images/logo.png",
"action": "start"
}'
Or if you want to start the audio post production in a separate request:
curl -X POST https://auphonic.com/api/production/{uuid}/start.json -u username:password
Creation of Presets
The creation of Presets is mostly equivalent, with the exception that you have to provide a preset_name
and that it’s not possible to add
chapters or an input file:
curl -X POST -H "Content-Type: application/json" \
https://auphonic.com/api/presets.json \
-u username:password \
-d '{
"preset_name": "The New Preset",
"metadata": {
"artist": "The Artist",
"album": "Our Album",
"subtitle": "Our subtitle",
"append_chapters": true,
"summary": "Our very long summary.",
"genre": "Podcast",
"year": 2012,
"publisher": "that's me",
"url": "https://auphonic.com",
"license": "Creative Commons Attribution 3.0 Austria",
"license_url": "http://creativecommons.org/licenses/by/3.0/at/",
"tags": ["preset", "auphonic api", "metadata", "tags"],
"location": {
"latitude": "47.070",
"longitude": "15.439"
}
},
"output_basename": "production-filename",
"output_files": [
{"format": "mp3", "bitrate": "64"},
{"format":"aac", "bitrate":"48"},
{"format": "flac"}
],
"outgoing_services": [{"uuid": "UC6aoChNZNt7KYZNxJTgUn"}],
"review_before_publishing": false,
"algorithms": {
"filtering": true, "leveler": true,
"normloudness": true, "denoise": true,
"loudnesstarget": -23, "denoiseamount": 100
},
"multi_input_files": [
{
"input_file": "http://your_server.com/intro.mp3",
"type": "intro"
},
{
"service": "pmefeNCzkyT4TbRbDmoCDf",
"input_file": "dropbox_outro_file.mp3",
"type": "outro"
}
],
"speech_recognition": {
"uuid": "6m8onAcvWHmZuJtDN6mzK8",
"keywords": ["Auphonic", "Holzmann", "Rattinger"],
"language": "de-DE",
"shownotes": true,
"shownotes_summary_example": "This is an example summary."
},
"image": "https://auphonic.com/static/images/logo.png"
}'
Furthermore you can change and update existing presets with the command:
https://auphonic.com/api/preset/{uuid}/{command}.json
where command
should be one of metadata
, output_files
, outgoing_services
,
multi_input_files
, algorithms
, speech_recognition
or upload
.