Recommended for software engineers only ! 😉
Draft version - last updated 2022-10-25
Upload
You can use our API /api/v1/import/upload/ to ingest new tracks.
In a JSON string you specify the metadata.
You can (a) upload the audio file with the API call or (b) specify a url in the JSON string ("url_audio").
Mandatory fields in the JSON string are:
| field | comment |
| id_client | unique identifier for a track in your system/platform/database |
| url_audio | url where we can download the audio file. If the file is on AWS S3 and not public, create a signed url valid for 7 days. Important: If you upload a file, leave the value empty or omit the field url_audio. If you upload a file and provide a url, the API will respond with an error. |
| label_name | name of the label or catalog |
| album_name | name of the album |
| title | title of the track |
| composer | composer(s) of the track. Important: if you list the writers/composers in the writers array (first_name, last_name...), too, we will use that information instead and you can omit the field composer. |
All other fields are optional.
All fields are type string except:
| field | type |
| track_number | int |
| bpm | int |
| ownership_share | int |
| maintracknumber |
int |
JSON fields
| field | comment |
| hook_url | url we call once the track has been processed |
| id_client | unique identifier for a track in your system/platform/database |
| url_audio | url where we can download the audio file. If the file is on AWS S3 and not public, create a signed url valid for 7 days. Important: If you upload a file, leave the value empty or omit the field url_audio. If you upload a file and provide a url, the API will respond with an error. |
| url_album_image | url where we can download the album image. If the file is on AWS S3 and not public, create a signed url valid for 7 days. If no url is provided we will try to use the album image from the ID3 tag (if available) in the audio file. |
| label_name | name of the label or catalog, db_name: label |
| label_code | label code, db_name: labelcode |
| label_lc_name | label code name |
| album_name | name of the album, db_name: LibraryCDTitle |
| album_code | code or number of the album, db_name: LibraryCDno |
| album_description | description for the album, db_name: LibraryCDdescription |
| title | title of the track |
| track_number | number of the track, db_name: track |
| track_version | version of the track. e.g. Main , db_name: trackversion |
| has_vocals | possible values: yes, no |
| explicit | possible values: yes, no |
| music_key | e.g. D#m |
| music_meter | e.g. 4/4 |
| mainversion | possible values: yes, no |
| trackspertitle | track numbers of alternate versions in the same album, comma delimited. e.g. 15,24,39. You can instead use maintracknumber, which is often available on 3rd party platforms. Used to link alternate versions to the main version. |
| maintracknumber |
when mainversion = no, specify the track_number of the main version. e.g. 4. Used to link alternate versions to the main version. |
| lyrics | make sure you encode special characters like line breaks etc. |
| lyrics_language | e.g.: en |
| description | description of track |
| keywords | keywords for track |
| bpm | beats per minute |
| tempo | tempo of track , db_name: tempos |
| isrc | ISRC |
| iswc | ISWC |
| release_date | format as YYYY-MM-DD e.g. 2022-12-30, db_name: releasedate |
| moods | comma delimited list of moods for track. e.g. Dark, Heroic, Tragic, Powerful |
| genres | comma delimited list of genres for track , db_name: music_styles |
| music_for | comma delimited list of words that describe what the track can be best used for. e.g. Documentaries , News |
| style_of | comma delimited list of words the track is similar to. e.g. American Beauty. db_name: well_known_tunes |
| featured_instruments | comma delimited list of (featured) instruments for track , db_name: instruments |
| artist | artist name |
| composer | comma delimited list of composer(s) of the track. if you list the writers/composers in the writers array (first_name, last_name...), we will use writers information instead and you can omit the field composer. |
| publisher | comma delimited list of publisher(s) of the track. if you list the publishers in the publishers array, too, we will use that information instead and you can omit the field publisher. |
| writers | array of writer(s). last_name is madatory. See JSON example for more information |
| publishers | array of publisher(s). See JSON example for more information |
JSON example:
{
"hook_url":"https://www.example.com/api/hook/",
"id_client":"985698349_AHN",
"url_audio": "https://www.example.com/sample.wav",
"url_album_image": "https://www.example.com/albumimage.jpg",
"label_name": "Voice",
"label_code": "",
"label_lc_name": "",
"album_name": "Voice - Compilation",
"album_code": "VMV030",
"album_description": "A variety for every need, from promos to ads, film and trailers, games and documentaries",
"title": "Final Hour",
"track_number": "1",
"track_version": "Full",
"has_vocals": "no",
"explicit": "no",
"music_key":"D#m",
"music_meter":"4/4",
"mainversion": "yes",
"lyrics": "dancing in the sun",
"lyrics_language": "en",
"description": "confident, attitude, assertive, bold",
"keywords": "",
"bpm": "76",
"tempo": "slow",
"isrc": "QM-GWH-13-00040",
"iswc": "",
"release_date": "2022-12-31",
"moods": "dramatic, mysterious",
"genres": "Soundtrack, Score",
"music_for": "Documentaries, News",
"style_of":"American Beauty",
"featured_instruments": "hammond",
"artist": "",
"composer": "Karina Tammy Byrne (PRS),DURIEUX (PRS)",
"publisher": "Cavendish Music Library (PRS)",
"writers": [
{
"first_name": "Karina Tammy",
"last_name": "Byrne",
"pro_affiliation": "PRS",
"ownership_share": "50",
"cae_ipi": "872609216"
},
{
"first_name": "",
"last_name": "DURIEUX",
"pro_affiliation": "PRS",
"ownership_share": "50",
"cae_ipi": "1101541034"
}
],
"publishers": [
{
"company_name": "Cavendish Music Library",
"pro_affiliation": "PRS",
"ownership_share": "100",
"cae_ipi": "1007849852",
"role": "Original Publisher",
"territory": "world"
}
]
}
Webhooks
Specify the hook_url field in the request. The processing pipeline will call this URL once it processes the track.
0 Comments