";
int timeout = 5 * 1000; // ms
byte[] wavFile = File.ReadAllBytes("x.mp3");
// var fileStream = new FileStream(filePath, FileMode.Open);
string method = "POST";
string sigVersion = "1";
string timestamp = DateTime.Now.Ticks.ToString();
string sigStr = method + "\n" + endpoint + "\n" + accessKey + "\n" + dataType + "\n" + sigVersion + "\n" + timestamp;
string signature = ComputeSignature(Encoding.ASCII.GetBytes(sigStr), Encoding.ASCII.GetBytes(accessSecret));
Console.WriteLine(signature);
var formContent = new MultipartFormDataContent();
formContent.Add(new StringContent(accessKey), "\"access_key\"");
formContent.Add(new StringContent(timestamp), "\"timestamp\"");
formContent.Add(new StringContent(signature), "\"signature\"");
formContent.Add(new StringContent(dataType), "\"data_type\"");
formContent.Add(new StringContent(sigVersion), "\"signature_version\"");
formContent.Add(new StringContent(wavFile.Length.ToString()), "\"sample_bytes\"");
var filestream = new ByteArrayContent(wavFile, 0, wavFile.Length);
filestream.Headers.Add("Content-Type", "application/octet-stream");
formContent.Add(filestream, "\"sample\"");
HttpClient client = new HttpClient();
var httpresponse = await client.PostAsync('https://'+host+"/v1/identify", formContent);
string responseBody = await httpresponse.Content.ReadAsStringAsync();
Console.WriteLine(responseBody);
}
static string ComputeSignature(byte[] body, byte[] secret)
{
HMACSHA1 hmac = new HMACSHA1(System.Text.Encoding.UTF8.GetBytes(secret));
byte[] stringBytes = Encoding.UTF8.GetBytes(body);
byte[] hashedValue = hmac.ComputeHash(stringBytes);
string res = Convert.ToBase64String(hashedValue, 0, hashedValue.Length);
return res;
}
}
}
```
````
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="200 " %}
```
{
"metadata":{
"timestamp_utc":"2020-01-19 02:58:28",
"music":[
{
"db_begin_time_offset_ms":0,
"db_end_time_offset_ms":9280,
"sample_begin_time_offset_ms":0,
"sample_end_time_offset_ms":9280,
"play_offset_ms":9040,
"artists":[
{
"name":"Adele",
"langs":[{"code":"zh-Hans", "name":"阿黛尔"}]
}
],
"lyrics":{
"copyrights":[
"Sony/ATV Music Publishing LLC",
"Universal Music Publishing Group"
]
},
"acrid":"6049f11da7095e8bb8266871d4a70873",
"album":{
"name":"Hello",
"langs":[{"code":"zh-Hans","name":"Hello"}]
},
"rights_claim": [
{"distributor":{"id":"PADPIDA2007050901U", "name":"Warner Music Group"},"rights_owners":[{"name":"Warner Music Group", "share_percentage":100.00}],"rights_claim_policy":"monetize", "territories":["AD","AE","AF"]},
{"distributor":{"id":"PADPIDA2007040502I", "name":"Sony Music Entertainment"}, "rights_owners":[{"name":"Sony Music Entertainment", "share_percentage":100.00}],"territories":["AB","AC"]}
],
"external_ids":{
"iswc":"T-917.819.808-8",
"isrc":"GBBKS1500214",
"upc":"886445581959"
},
"result_from":3,
"contributors":{
"composers":[
"Adele Adkins",
"Greg Kurstin"
],
"lyricists":[
"ADELE ADKINS",
"GREGORY KURSTIN"
]
},
"title":"Hello",
"langs":[{"code":"zh-Hans","name":"Hello"}]
"language":"en",
"duration_ms":295000,
"label":"XL Recording",
"external_metadata":{
"musicbrainz":[
{
"track":{
"id":"0a8e8d55-4b83-4f8a-9732-fbb5ded9f344"
}
}
],
"deezer":{
"track":{
"id":"110265034"
},
"artists":[
{
"id":"75798"
}
],
"album":{
"id":"11483764"
}
},
"spotify":{
"track":{
"id":"4aebBr4JAihzJQR0CiIZJv"
},
"artists":[
{
"id":"4dpARuHxo51G3z768sgnrY"
}
],
"album":{
"id":"7uwTHXmFa1Ebi5flqBosig"
}
},
"musicstory":{
"track":{
"id":"13106540"
},
"album":{
"id":"931271"
}
},
"youtube":{
"vid":"YQHsXMglC9A"
}
},
"score":100,
"genres":[{"name":"Pop"}],
"release_date":"2015-10-23"
"release_by_territories": [{"territories": ["DK"], "release_date": "2006-04-17"}, {"territories": ["JP"], "release_date": "2006-10-17"}, {"territories": ["SE"], "release_date": "2005-06-21"}, {"territories": ["BG", "AL", "BA", "CZ", "EE", "HR", "HU", "LT", "LV", "MK", "ME", "PL", "RO", "RS", "SI", "SK", "UA"], "release_date": "2006-03-24"}, {"territories": ["GB", "IE", "NZ"], "release_date": "2005-07-18"}, {"territories": ["FR"], "release_date": "2005-07-26"}]
}
],
"custom_files": [
{
"acrid":"e6f7e3884b00fd265871754c5b64782b",
"title":"YOUR_TITLE",
"bucket_id":999,
"duration_ms":295000,
"db_begin_time_offset_ms":0,
"db_end_time_offset_ms":9280,
"sample_begin_time_offset_ms":0,
"sample_end_time_offset_ms":9280,
"key1":"value1", //custom-defined
"key2":"value2" //custom-defined
}
]
},
"status":{
"msg":"Success",
"version":"1.0",
"code":0
},
"result_type":0
}
```
{% endtab %}
{% endtabs %}
##
# Metadata
# Music
An example of music metadata for Audio & Video Recognition project
### JSON structure
```json
{
"metadata": {
"timestamp_utc": "2020-01-19 02:58:28",
"music": [
{
"db_begin_time_offset_ms": 0,
"db_end_time_offset_ms": 9280,
"sample_begin_time_offset_ms": 0,
"sample_end_time_offset_ms": 9280,
"play_offset_ms": 9040,
"artists": [
{
"name": "Adele",
"langs": [
{
"code": "zh-Hans",
"name": "阿黛尔"
}
]
}
],
"acrid": "6049f11da7095e8bb8266871d4a70873",
"album": {
"name": "Hello",
"langs": [
{
"code": "zh-Hans",
"name": "Hello"
}
]
},
"rights_claim": [
{
"distributor": {
"id": "PADPIDA2007050901U",
"name": "Warner Music Group"
},
"rights_owners": [
{
"name": "Warner Music Group",
"share_percentage": 100
}
],
"rights_claim_policy": "monetize",
"territories": [
"AD",
"AE",
"AF"
]
},
{
"distributor": {
"id": "PADPIDA2007040502I",
"name": "Sony Music Entertainment"
},
"rights_owners": [
{
"name": "Sony Music Entertainment",
"share_percentage": 100
}
],
"territories": [
"AB",
"AC"
]
}
],
"external_ids": {
"iswc": "T9178198088",
"isrc": "GBBKS1500214",
"upc": "886445581959"
},
"result_from": 3,
"contributors": {
"composers": [
"Adele Adkins",
"Greg Kurstin"
],
"lyricists": [
"ADELE ADKINS",
"GREGORY KURSTIN"
]
},
"title": "Hello",
"langs": [
{
"code": "zh-Hans",
"name": "Hello"
}
],
"language": "en",
"duration_ms": 295000,
"label": "XL Recording",
"external_metadata": {
"musicbrainz": {
"track": {
"id": "0a8e8d55-4b83-4f8a-9732-fbb5ded9f344"
}
},
"deezer": {
"track": {
"id": "110265034"
},
"artists": [
{
"id": "75798"
}
],
"album": {
"id": "11483764"
}
},
"spotify": {
"track": {
"id": "4aebBr4JAihzJQR0CiIZJv"
},
"artists": [
{
"id": "4dpARuHxo51G3z768sgnrY"
}
],
"album": {
"id": "7uwTHXmFa1Ebi5flqBosig"
}
},
"youtube": {
"vid": "YQHsXMglC9A"
}
},
"score": 100,
"genres": [
{
"name": "Pop"
}
],
"release_date": "2015-10-23",
"works": [
{
"iswc": "T9178198088",
"name": "HELLO",
"creators": [
{
"name": "KURSTIN GREGORY ALLEN",
"last_name": "KURSTIN",
"ipi": 122619891,
"roles": [
"Composer"
]
},
{
"name": "ADKINS ADELE LAURIE BLUE",
"last_name": "ADKINS",
"ipi": 544476240,
"roles": [
"Composer"
]
},
{
"name": "EMI APRIL MUSIC INC ",
"last_name": "EMI APRIL MUSIC INC",
"ipi": 128633767,
"roles": [
"Publisher"
]
},
{
"name": "KURSTIN MUSIC ",
"last_name": "KURSTIN MUSIC",
"ipi": 485851707,
"roles": [
"Publisher"
]
},
{
"name": "MELTED STONE PUBLISHING LTD ",
"last_name": "MELTED STONE PUBLISHING LTD",
"ipi": 676466696,
"roles": [
"Publisher"
]
}
]
}
]
}
]
},
"status": {
"msg": "Success",
"version": "1.0",
"code": 0
}
}
```
### Metadata fields
| Name | Description |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| music | Music fields |
| acrid | ACRCloud unique identifier |
| timestamp\_utc | Server time of sending results, Timestamp of the song started for custom monitoring, UTC time zone |
| title | Track title |
| album | Album fields |
| id | Identifier of the artists , album or 3rd parties fields |
| name | Name of the artists or album |
| artists | Artists fields |
| duration\_ms | Duration of the track in millisecond |
| play\_offset\_ms | The time position of the audio/song being played (millisecond) |
| external\_ids | External standard code |
| isrc | ISRC code |
| upc | UPC code |
| external\_metadata | External 3rd party IDs and metadata |
| track | Track fields |
| genres | Genres fields |
| label | Music label name |
| release\_date | Release data of the track, format:YYYY-MM-DD |
| spotify | Spotify fields |
| deezer | Deezer fields |
| lyricfind | LyricFind fields |
| lfid | LyricsFind's lyric ID |
| youtube | YouTube fields |
| vid | Youtube video ID |
| musicbrainz | MusicBrainz Identifier - MBID |
| db\_begin\_time\_offset\_ms | Position of beginning of the recognition on database file (millisecond) |
| db\_end\_time\_offset\_ms | Position of end of the recognition on database file (millisecond) |
| sample\_begin\_time\_offset\_ms | Position of beginning of the recognition in sample file sent by SDK/API (millisecond) |
| sample\_end\_time\_offset\_ms | Position of end of the recognition in sample file sent by SDK/API (millisecond) |
| played\_duration | Actual duration of the track played in the streams for Broadcast Monitoring service, in second |
| score | Match confidence score. Range: 70 - 100 |
| +contributors | Contributor information for this track |
| +composers | Composers of the song |
| +lyricists | Writers of the lyrics |
| language | Language of the song, ISO 639-1 codes |
| langs | Translation into different languages. Example: \[{"code":"ru", "name":"Я твой враг"}] |
| #rights\_claim | All relevant metadata fields to determine rights owners, available territories and rights claim policy for UGC platforms. These metadata fields are for copyright compliance users only. |
| #distributor | Information of distributor for this track |
| #id | DDEX Party ID of the distributor, this ID won't change. |
| #name | Name of the distributor, This name might be changing from time to time. |
| #rights\_claim\_policy | Right policy for UGC platforms, the value options are "Monetize", "Allow", "ReportUsage" and "BlockAccess". |
| #rights\_owners | Rights owners' name, example: \[{"name":"Warner Music Group", "share\_percentage":100}] |
| #territories | Territory codes for Included territories, ISO country codes applied. |
| #excluded\_territories | Territory codes for excluded territories, ISO country codes applied. |
| #share\_percentage | Percentage of the rights share for each rights owners. |
| #release\_by\_territories | Release details by territories, indicate the release date for territories. |
| +work | Publishing metadata fields for works |
| +ISWC | ISWC code |
| +name | Name of the work |
| +creators | The creators of the work |
| +ipi | IPI code for the creator |
| +roles | The roles of the creator |
| time\_skew | Time skew refers to a temporal misalignment or timing offset between two audio signals. It means that the audio events (such as beats, notes, or spectral features) occur earlier or later in time than expected. |
| frequency\_skew | Frequency skew refers to a distortion in the frequency domain, where the spectral components of the audio are shifted upward or downward in frequency. |
{% hint style="info" %}
**Please note: Only *****ACRID,*** ***Track Title, Artists Name, Album Name***** and \*\_time\_offset\_ms fields are required, other fields are optional.**
\#fields are visible for the projects with copyright compliance option only.
+fields are visible upon request, please contact us if you need those fields.
{% endhint %}
# Custom Files
An example of custom-defined metadata for Audio & Video Recognition, Broadcast Monitoring, Hybrid Recognition and Offline Recognition projects.
### JSON structure
```json
{
"metadata": {
"timestamp_utc": "2020-01-19 02:58:28",
"custom_files": [
{
"bucket_id": "51",
"title": "You are beautiful",
"artist": "James",
"acrid": "5343bc191634b042622bf474ed46121a",
"audio_id": "3"
}
]
},
"status": {
"msg": "Success",
"version": "1.0",
"code": 0
}
}
```
### Metadata fields
| Name | Description |
| --------------------------------- | ------------------------------------------------------------------------------------- |
| custom\_files | Custom uploaded file fields |
| arcid | ACRCloud unique identifier |
| title | File name |
| audio\_id | User defined identifier |
| play\_offset\_ms | Position of the recognition in the file if the file was playing (millisecond) |
| \*db\_begin\_time\_offset\_ms | Position of beginning of the recognition on database file (millisecond) |
| \*db\_end\_time\_offset\_ms | Position of end of the recognition on database file (millisecond) |
| \*sample\_begin\_time\_offset\_ms | Position of beginning of the recognition in sample file sent by SDK/API (millisecond) |
| \*sample\_end\_time\_offset\_ms | Position of end of the recognition in sample file sent by SDK/API (millisecond) |
{% hint style="info" %}
***\* fields are visible in Broadcast Monitoring service only, if you want to use these fields in recognition service, please contact us.***
**Please note: Only *****Title, ARCID, Audio\_ID***** are required fields.**
{% endhint %}
# Live Channels
An example of live channels detection metadata for Live Channel Detection and Hybrid Recognition projects
### JSON structure
```json
{
"metadata": {
"custom_streams": [
{
"title": "xxxxxxxxxx",
"acrid": "xxxxxxxxxx",
"timestamps_ms": "1491987674",
"result_type": "live",
"score": 100
}
]
},
"status": {
"msg": "Success",
"version": "1.0",
"code": 0
}
}
```
| Name | Description |
| --------------- | -------------------------------------------------- |
| streams | ACRCloud Live channel fields |
| custom\_streams | Custom live channel fields |
| arcid | ACRCloud unique identifier |
| score | Match score, 60-100 |
| title | Live channel name |
| timestamps\_ms | Unix Timestamp (UTC) in milliseconds of live feeds |
| result\_type | "live" or "timeshift" |
# Humming
An example of humming metadata for Audio & Video Recognition project
### JSON structure
```bash
{
"metadata": {
"humming": [
{
"external_ids": {
},
"title": "As Long As You Love Me",
"artists": [
{
"name": "Backstreet Boys"
}
],
"acrid": "2167d4c8d51d2944881be2fc128372f6",
"external_metadata": {
"deezer": {
"album": {
"id": "76662",
"name": "Beautiful"
},
"artists": [
{
"name": "Backstreet Boys",
"id": "330"
}
],
"track": {
"name": "As Long As You Love Me",
"id": "602351"
}
},
"spotify": {
"album": {
"id": "1c7PDfu5CEUWE5M79pSHeD",
"name": "Race For Life The Official Soundtrack 2011"
},
"artists": [
{
"name": "Backstreet Boys",
"id": "5rSXSAkZ67PYJSvpUpkOr7"
}
],
"track": {
"name": "As Long as You Love Me",
"id": "11Oj3hu53ZVOqzcw35elvh"
}
},
"youtube": {
"vid": "0Gl2QnHNpkA"
}
},
"album": {
"name": "Beautiful"
},
"score": "0.88"
},
{
"external_ids": {
},
"external_metadata": {
},
"score": "0.87",
"title": "As Long As You Love Me",
"duration_ms": "213093",
"genres": [
{
"name": "Pop"
}
],
"acrid": "d4c6ff541580d20c7f35ef4a390eac41",
"album": {
"name": "Beautiful"
},
"artists": [
{
"name": "Backstreet Boys"
}
]
},
{
"external_ids": {
},
"title": "If You Love Me",
"artists": [
{
"name": "Kys"
}
],
"external_metadata": {
},
"acrid": "103fc2e9df3712151bb9601189fe3751",
"album": {
"name": ""
},
"score": "0.67"
},
{
"external_ids": {
},
"external_metadata": {
},
"score": "0.64",
"title": "Hurt (Album Version)",
"duration_ms": "243626",
"genres": [
{
"name": "Pop"
}
],
"acrid": "2c7939c273ac5b83922b0d7be45d0743",
"album": {
"name": "Hurt"
},
"artists": [
{
"name": "Christina Aguilera"
}
]
},
{
"external_ids": {
},
"title": "打开爱",
"artists": [
{
"name": "Vee"
}
],
"external_metadata": {
},
"acrid": "7c23c2f6b9d7c8eb5cc0b877e1782691",
"album": {
"name": ""
},
"score": "0.62"
}
]
},
"status": {
"msg": "Success",
"version": "1.0",
"code": 0
}
}
```
### Metadata fields
| Name | Description |
| ------------------ | --------------------------------------------- |
| humming | Humming Recognition fields |
| acrid | ACRCloud unique identifier |
| timestamp\_utc | Server time of sending results, UTC time zone |
| score | Humming score |
| title | Track title |
| album | Album fields |
| id | Identifier of the artists or album |
| name | Name of the artists or album |
| artists | Artists fields |
| duration\_ms | Duration of the track in millisecond |
| play\_offset\_ms | Position of the recognition in millisecond |
| external\_ids | External standard code |
| isrc | ISRC code |
| upc | UPC code |
| external\_metadata | External 3rd party IDs and metadata |
| track | Track fields |
| genres | Genres fields |
{% hint style="info" %}
Only ACRID, Title, Artist and Score are required fields.
{% endhint %}
# Music/Speech Detection
An example of music/speech detection metadata for FS project.
```json
{
"music_speech":[
{
"start": 0,
"end": 247,
"label": "m"
}
]
}
```
# Console API
# Access Token
## How to get the access token
Create the token in the [console developer setting](https://console.acrcloud.com/account#/developer)
# Buckets
## Create a bucket
`POST` `https://api-v2.acrcloud.com/api/buckets`
Create an empty bucket, then you can upload audio files or add channels to this bucket to create your fingerprint database.
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
#### Request Body
| Name | Type | Description |
| ------------------ | ------ | ---------------------------------------------------------------- |
| name | string | The bucket name |
| region | string | eu-west-1,us-west-2,ap-southeast-1 |
| type | string | File,Live,LiveRec,LiveTimeshift |
| net\_type | number | 0,1,2 |
| labels | array | The labels for the bucket. For examples: \["Music", "Comercial"] |
| metadata\_template | string | Metadata template |
{% tabs %}
{% tab title="201 " %}
```
{
"data": {
"id": 8881,
"uid": 1,
"name": "bucket_music",
"type": "File",
"node": "127.0.0.1-871",
"state": 1,
"region": "ap-southeast-1",
"metadata_template": "{\"artist\":{\"default\":\"abc\"}, \"album\":{\n\"type\":\"select\", \"default\":\"334\", \"options\":[\"123\", \"334\"]}}",
"labels": [
"Music",
"Video"
],
"net_type": 1,
"created_at": "2019-03-01 15:31:25",
"updated_at": "2019-08-16 07:17:32",
"num": 10,
"size": "300000",
"access_permission": "private"
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request POST 'https://api-v2.acrcloud.com/api/buckets' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{
"name":"avbucket",
"type":"File",
"labels":["Music", "Video"],
"net_type":1,
"region":"ap-southeast-1"
}'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api-v2.acrcloud.com/api/buckets"
data={"name":"avbucket",
"type":"File",
"labels":["Music", "Video"],
"net_type":1,
"region":"ap-southeast-1"
}
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer token'
}
response = requests.post(url, headers=headers, json=data)
print(response.text)
```
{% endtab %}
{% tab title="PHP" %}
```php
'https://api-v2.acrcloud.com/api/buckets',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => array('name' => 'testbucket','region' => 'ap-southeast-1','type' => 'File'),
CURLOPT_HTTPHEADER => array(
'Accept: application/json',
'Authorization: Bearer token'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
```
{% endtab %}
{% tab title="Nodejs" %}
```javascript
var axios = require('axios');
var data = JSON.stringify({"name":"avbucket","type":"File","labels":["Music","Video"],"net_type":1,"region":"ap-southeast-1"});
var config = {
method: 'post',
url: 'https://api-v2.acrcloud.com/api/buckets',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
},
data : data
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
```
{% endtab %}
{% endtabs %}
## List Buckets
`GET` `https://api-v2.acrcloud.com/api/buckets`
Return a list of your buckets.
#### Query Parameters
| Name | Type | Description |
| --------- | ------ | ------------------------------------------ |
| page | number | The page number |
| per\_page | number | The results number per page. Default is 20 |
| region | string | eu-west-1,us-west-2,ap-southeast-1 |
| type | string | File,Live,LiveRec,LiveTimeshift |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
```
{
"data": [
{
"id": 14791,
"uid": 19,
"name": "test",
"type": "Live",
"state": 1,
"region": "eu-west-1",
"metadata_template": null,
"labels": [
"TV"
],
"net_type": 1,
"created_at": "2020-07-16 11:09:20",
"updated_at": "2020-07-16 11:09:20",
"num": 0,
"size": 0,
"access_permission": "private"
},
{
"id": 14556,
"uid": 19,
"name": "adsfasdf",
"type": "LiveTimeshift",
"state": 1,
"region": "eu-west-1",
"metadata_template": "",
"labels": [
""
],
"net_type": 1,
"created_at": "2020-06-24 11:07:00",
"updated_at": "2020-06-24 11:07:00",
"num": 0,
"size": 0,
"access_permission": "private"
},
{
"id": 12310,
"uid": 19,
"name": "eu_shared_bucket2",
"type": "LiveRec",
"state": 1,
"region": "eu-west-1",
"metadata_template": "",
"labels": [
"Radio"
],
"net_type": 1,
"created_at": "2019-10-30 07:54:56",
"updated_at": "2019-10-30 07:54:56",
"num": 0,
"size": 0,
"access_permission": "private"
},
{
"id": 12309,
"uid": 19,
"name": "eu_shared_bucket",
"type": "LiveRec",
"node": "",
"state": 1,
"region": "eu-west-1",
"metadata_template": "",
"labels": [
"Radio"
],
"net_type": 1,
"created_at": "2019-10-30 07:53:58",
"updated_at": "2019-10-30 07:53:58",
"num": 0,
"size": 0,
"access_permission": "private"
},
{
"id": 1159,
"uid": 19,
"name": "us_bucket",
"type": "File",
"state": 1,
"region": "global",
"metadata_template": "",
"labels": [
"Music"
],
"net_type": 0,
"created_at": "2016-05-11 06:49:55",
"updated_at": "2017-07-17 11:48:06",
"num": 7,
"size": "1487",
"access_permission": "private"
},
{
"id": 1116,
"uid": 19,
"name": "offline-bucket",
"type": "File",
"node": "10.12.12.236-850",
"state": 1,
"region": "eu-west-1",
"metadata_template": "",
"labels": [
"Music"
],
"net_type": 2,
"created_at": "2016-05-01 07:10:16",
"updated_at": "2018-01-05 16:41:15",
"num": 0,
"size": 0,
"access_permission": "private"
}
],
"links": {
"first": "https://api-v2.acrcloud.com/api/buckets?page=1",
"last": "https://api-v2.acrcloud.com/api/buckets?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "https://api-v2.acrcloud.com/api/buckets",
"per_page": 20,
"to": 6,
"total": 6
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
equest GET 'https://api-v2.acrcloud.com/api/buckets?region=eu-west-1' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api-v2.acrcloud.com/api/buckets?region=eu-west-1"
payload={}
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
{% endtab %}
{% tab title="PHP" %}
```php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api-v2.acrcloud.com/api/buckets?region=eu-west-1',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Accept: application/json',
'Authorization: Bearer token'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
```
{% endtab %}
{% tab title="Nodejs" %}
```javascript
var data = qs.stringify({
});
var config = {
method: 'get',
url: 'https://api-v2.acrcloud.com/api/buckets?region=eu-west-1',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer token'
},
data : data
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
```
{% endtab %}
{% endtabs %}
## Get a bucket
`GET` `https://api-v2.acrcloud.com/api/buckets/:id`
Get the details of a bucket.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------- |
| id | number | The bucket id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"id": 8881,
"uid": 1,
"name": "bucket_music",
"type": "File",
"node": "127.0.0.1-871",
"state": 1,
"region": "ap-southeast-1",
"metadata_template": "{\"artist\":{\"default\":\"abc\"}, \"album\":{\n\"type\":\"select\", \"default\":\"334\", \"options\":[\"123\", \"334\"]}}",
"labels": [
"Music",
"Video"
],
"net_type": 1,
"created_at": "2019-03-01 15:31:25",
"updated_at": "2019-08-16 07:17:32",
"num": 10,
"size": "300000",
"access_permission": "private"
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --request GET 'https://api-v2.acrcloud.com/api/buckets/8881' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer your_access_token'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api-v2.acrcloud.com/api/buckets/966"
payload={}
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer your_access_token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
{% endtab %}
{% tab title="PHP" %}
```php
'https://api-v2.acrcloud.com/api/buckets/966',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Accept: application/json',
'Authorization: Bearer your_access_token'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
var axios = require('axios');
var config = {
method: 'get',
url: 'https://api-v2.acrcloud.com/api/buckets/966',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer your_access_token'
}
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
```
{% endtab %}
{% tab title="Nodejs" %}
```javascript
var axios = require('axios');
var config = {
method: 'get',
url: 'https://api-v2.acrcloud.com/api/buckets/966',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer your_access_token'
}
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
```
{% endtab %}
{% endtabs %}
## Update a bucket
`PUT` `https://api-v2.acrcloud.com/api/buckets/:id`
Update the details of the bucket.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------- |
| id | number | The bucket id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
#### Request Body
| Name | Type | Description |
| ------------------ | ------ | ----------------------------- |
| metadata\_template | string | Update the metadata\_template |
| labels | string | Update the labels |
| name | string | Update the bucket name |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"id": 8881,
"uid": 1,
"name": "bucket_music",
"type": "File",
"node": "127.0.0.1-871",
"state": 1,
"region": "ap-southeast-1",
"metadata_template": "{\"artist\":{\"default\":\"abc\"}, \"album\":{\n\"type\":\"select\", \"default\":\"334\", \"options\":[\"123\", \"334\"]}}",
"labels": [
"Music",
"Video"
],
"net_type": 1,
"created_at": "2019-03-01 15:31:25",
"updated_at": "2019-08-16 07:17:32",
"num": 10,
"size": "300000",
"access_permission": "private"
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request PUT 'https://api-v2.acrcloud.com/api/buckets/8881' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{"name":"bucket-music"}'
```
{% endtab %}
{% endtabs %}
## Delete the bucket
`DELETE` `https://api-v2.acrcloud.com/api/buckets/:id`
Before you delete the bucket, you need to clean the bucket first.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------- |
| id | number | The bucket id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="204 " %}
```
```
{% endtab %}
{% endtabs %}
# Audio Files
## Upload an audio file/fingerprint
`POST` `https://api-{bucket-region}.acrcloud.com/api/buckets/:bucket_id/files`
Upload the audio files or fingerprint to the specified bucket
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | ------------- |
| bucket\_id | number | The bucket id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
#### Request Body
| Name | Type | Description |
| ------------- | ------ | --------------------------------------------------------------------------------- |
| file | object | The audio or fingerprint file. Required if the data\_type is audio or fingerprint |
| title | string | The title of this file |
| data\_type | string | the file type, the value should be audio, fingerprint, audio\_url or acrid |
| user\_defined | string | The user-defined metadata. JSON format. |
| url | string | audio file download URL. required if the data\_*type is audio\_*url |
| acrid | String | acrid from ACRCloud Music Database |
{% tabs %}
{% tab title="200 File successfully uploaded." %}
```
{
"data": {
"uid": 1,
"acr_id": "6d3e17559677cd79ecb0b7cd2c79bea0",
"bucket_id": 8891,
"state": 0,
"title": "adsfad",
"audio_id": "",
"duration": "78.524082",
"user_defined": {},
"updated_at": "2020-12-24T08:49:17.000000Z",
"created_at": "2020-12-24T08:49:17.000000Z",
"id": 20
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request POST 'https://api-v2.acrcloud.com/api/buckets/8891/files' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--form 'file=@"/Users/olym/Downloads/test.mp3"' \
--form 'title="adsfad"' \
--form 'data_type="audio"'
curl --location --request POST 'https://api-v2.acrcloud.com/api/buckets/8891/files' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{"data_type":"audio_url", "title":"file-title", "user_defined":{"artists":"artist"}, "url":"https://your_host.com/AEA040700015_T1.mp3"}'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
import json
url = "https://api-v2.acrcloud.com/api/buckets/8891/files"
payload={'title': 'adsfad','data_type': 'audio',"user_defined":json.dumps({"key1":"value1", "key2":"value2"})}
files=[
('file',('test.mp3',open('/Users/olym/Downloads/test.mp3','rb'),'audio/mpeg'))
]
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer token'
}
response = requests.request("POST", url,
headers=headers,
data=payload,
files=files)
print(response.text)
```
{% endtab %}
{% tab title="PHP" %}
```php
'https://api-v2.acrcloud.com/api/buckets/8891/files',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => array('file'=> new CURLFILE('/Users/olym/Downloads/test.mp3'),'title' => 'adsfad','data_type' => 'audio'),
CURLOPT_HTTPHEADER => array(
'Accept: application/json',
'Authorization: Bearer token'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
```
{% endtab %}
{% tab title="Nodejs" %}
```javascript
var axios = require('axios');
var FormData = require('form-data');
var fs = require('fs');
var data = new FormData();
data.append('file', fs.createReadStream('/Users/olym/Downloads/test.mp3'));
data.append('title', 'adsfad');
data.append('data_type', 'audio');
var config = {
method: 'post',
url: 'https://api-v2.acrcloud.com/api/buckets/8891/files',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer token',
...data.getHeaders()
},
data : data
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
```
{% endtab %}
{% tab title="Ruby" %}
```
require "uri"
require "net/http"
url = URI("https://api-v2.acrcloud.com/api/buckets/8891/files")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Accept"] = "application/json"
request["Authorization"] = "Bearer token"
form_data = [['file', File.open('/Users/olym/Downloads/test.mp3')],['title', 'adsfad'],['data_type', 'audio']]
request.set_form form_data, 'multipart/form-data'
response = http.request(request)
puts response.read_body
```
{% endtab %}
{% endtabs %}
## List the files
`GET` `https://api-{bucket-region}.acrcloud.com/api/buckets/:bucket_id/files`
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | ------------- |
| bucket\_id | string | The bucket id |
#### Query Parameters
| Name | Type | Description |
| --------- | ------ | ----------------------------------------------------------------------------- |
| search | string | search by title |
| sort | string | sort by id or status, default is sort by id |
| order | string | asc or desc, default is asc |
| page | number | The page number |
| per\_page | number | The results number per page |
| state | number | 0:processing
1:Ready (audio files have been processed)
-1: Error
|
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
```
{
"data": [
{
"id": 20,
"uid": 1,
"bucket_id": 8891,
"acr_id": "6d3e17559677cd79ecb0b7cd2c79bea0",
"state": 0,
"title": "adsfad",
"user_defined": {},
"duration": 79,
"audio_id": "",
"created_at": "2020-12-24T08:49:17.000000Z",
"updated_at": "2020-12-24T08:49:17.000000Z"
},
{
"id": 13,
"uid": 1,
"bucket_id": 8891,
"acr_id": "224b26f7e3a3c44858be896c0fd9f45f",
"state": 0,
"title": "adsfad2",
"user_defined": {},
"duration": 79,
"audio_id": "",
"created_at": "2020-12-20T21:43:34.000000Z",
"updated_at": "2020-12-20T21:43:49.000000Z"
},
{
"id": 12,
"uid": 1,
"bucket_id": 8891,
"acr_id": "0e5e7e376f7e177bbcb4da898f740a15",
"state": 0,
"title": "bucket",
"user_defined": {
"artist": "abc",
"album": "334",
"from": "ucf",
"played_duration": 8,
"ucf_id": "338229"
},
"duration": 206,
"audio_id": "",
"created_at": "2020-12-20T21:43:34.000000Z",
"updated_at": "2020-12-20T21:43:49.000000Z"
},
{
"id": 11,
"uid": 1,
"bucket_id": 8891,
"acr_id": "6c875f014b9ca0ae89f44e1f93151b05",
"state": 0,
"title": "adsfad",
"user_defined": {},
"duration": 10,
"audio_id": "",
"created_at": "2020-12-20T21:43:34.000000Z",
"updated_at": "2020-12-20T21:43:49.000000Z"
},
{
"id": 10,
"uid": 1,
"bucket_id": 8891,
"acr_id": "3ccdac434e9d08df333e8a5b4b8169fc",
"state": 0,
"title": "02c1d27e39",
"user_defined": {
"artist": "abc",
"album": "334",
"name": "asdf"
},
"duration": 14,
"audio_id": "",
"created_at": "2020-12-20T21:43:34.000000Z",
"updated_at": "2020-12-20T21:43:49.000000Z"
},
{
"id": 7,
"uid": 1,
"bucket_id": 8891,
"acr_id": "625b970b5b837326fc927bd14cbfceb5",
"state": 1,
"title": "ddddaa",
"user_defined": {},
"duration": 300,
"audio_id": "",
"created_at": "2020-12-20T21:43:34.000000Z",
"updated_at": "2020-12-20T21:43:49.000000Z"
},
{
"id": 6,
"uid": 1,
"bucket_id": 8891,
"acr_id": "87cd4888e660049f21199b812cc30346",
"fp_id": null,
"state": 1,
"title": "test",
"user_defined": {},
"duration": 300,
"audio_id": "",
"created_at": "2020-12-20T21:43:34.000000Z",
"updated_at": "2020-12-20T21:43:49.000000Z"
}
],
"links": {
"first": "http://127.0.0.1:8080/api/buckets/8891/files?page=1",
"last": "http://127.0.0.1:8080/api/buckets/8891/files?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "http://127.0.0.1:8080/api/buckets/8891/files",
"per_page": "20",
"to": 7,
"total": 7
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --request GET 'https://api-v2.acrcloud.com/api/buckets/8891/files' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api-v2.acrcloud.com/api/buckets/8891/files"
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer token'
}
response = requests.get(url, headers=headers)
print(response.text)
```
{% endtab %}
{% endtabs %}
## Update a file
`PUT` `https://api-{bucket-region}.acrcloud.com/api/buckets/:bucket_id/files/:id`
Update the metadata of a file
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | ------------------- |
| bucket\_id | number | The bucket id |
| id | number | The file id/acr\_id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
#### Request Body
| Name | Type | Description |
| ------------- | ------ | ----------------------------------- |
| title | string | The file title. |
| user\_defined | string | User-defined metadata, JSON format. |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"id": 20,
"uid": 1,
"bucket_id": 8891,
"acr_id": "6d3e17559677cd79ecb0b7cd2c79bea0",
"state": 0,
"title": "update-title",
"user_defined": {
"artists": "update-artist"
},
"duration": 79,
"audio_id": "",
"created_at": "2020-12-24T08:49:17.000000Z",
"updated_at": "2020-12-25T04:34:27.000000Z"
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request PUT 'https://api-v2.acrcloud.com/api/buckets/8891/files/20' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{"title":"update-title", "user_defined":{"artists":"update-artist"}}'
```
{% endtab %}
{% endtabs %}
## Delete files
`DELETE` `https://api-{bucket-region}.acrcloud.com/api/buckets/:bucket_id/files/:ids`
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | ------------------------------------- |
| bucket\_id | number | The bucket id |
| ids | number | The file ids/acrids, seperated by "," |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="204 " %}
```
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request DELETE 'https://api-v2.acrcloud.com/api/buckets/8891/files/12,13' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% endtabs %}
## Move the files to another bucket
`PUT` `https://api-{bucket-region}.acrcloud.com/api/buckets/:bucket_id/files/:ids/move`
Move the files to another bucket
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | ---------------------------------------------- |
| bucket\_id | number | The bucket id that you want move the files to. |
| ids | string | One or multiple ids/acrids, separated by "," |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="201 " %}
```
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request PUT 'https://api-v2.acrcloud.com/api/buckets/8892/files/12,13' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% endtabs %}
## Get one or multiple files
`GET` `https://api-{bucket-region}.acrcloud.com/api/buckets/:bucket_id/files/:ids`
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | ----------------------------------------- |
| ids | string | The files ids or acrids. Seperated by "," |
| bucket\_id | string | The bucket id |
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ------------ |
| Authorization\* | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
```
{
"data": [
{
"id": 12945472,
"uid": 19,
"bucket_id": 966,
"acr_id": "75806fee10cf4405de502435129d6c06",
"state": 1,
"title": "api-test",
"user_defined": {},
"duration": 174,
"created_at": "2020-10-14T11:02:15.000000Z",
"updated_at": "2020-10-14T11:02:15.000000Z",
"audio_id": "123"
},
{
"id": 12403501,
"uid": 19,
"bucket_id": 966,
"acr_id": "39a2d627dad781f5fbdb65e0e7d4d7c9",
"state": 1,
"title": "bucket-report-test",
"user_defined": {
"ucf_id": "718876"
},
"duration": 13,
"created_at": "2020-09-01T03:50:23.000000Z",
"updated_at": "2020-09-01T03:50:23.000000Z",
"audio_id": ""
},
{
"id": 12398516,
"uid": 19,
"bucket_id": 966,
"acr_id": "904475b22cc6ffe6692b07dcd65b8ef8",
"state": 1,
"title": "music",
"user_defined": {
"ucf_id": "725868"
},
"duration": 8,
"created_at": "2020-08-31T15:09:07.000000Z",
"updated_at": "2020-08-31T15:09:07.000000Z",
"audio_id": ""
},
{
"id": 12398474,
"uid": 19,
"bucket_id": 966,
"acr_id": "3b6fc496391a6a1758b6cd48da4f792b",
"state": 1,
"title": "happy",
"user_defined": {
"ucf_id": "718878"
},
"duration": 10,
"created_at": "2020-08-31T15:05:40.000000Z",
"updated_at": "2020-08-31T15:05:40.000000Z",
"audio_id": ""
},
{
"id": 12395185,
"uid": 19,
"bucket_id": 966,
"acr_id": "fe34ec4ffbcec033ec2ed050f4b0daa7",
"state": 1,
"title": "test",
"user_defined": {
"ucf_id": "690303"
},
"duration": 10,
"created_at": "2020-08-31T10:20:33.000000Z",
"updated_at": "2020-08-31T10:20:33.000000Z",
"audio_id": ""
},
{
"id": 12158027,
"uid": 19,
"bucket_id": 966,
"acr_id": "d66a31c5e62cf3e86874476da60db641",
"state": 1,
"title": "test",
"user_defined": {
"type": "advert",
"from": "ucf",
"played_duration": 16,
"ucf_id": "725869"
},
"duration": 30,
"created_at": "2020-08-11T04:03:31.000000Z",
"updated_at": "2020-08-11T04:03:31.000000Z",
"audio_id": ""
},
{
"id": 11163949,
"uid": 19,
"bucket_id": 966,
"acr_id": "601a566c3d4d77dfdb220e750384f842",
"state": 1,
"title": "Kesayanganku",
"user_defined": {
"artist": "Al Ghazali",
"from": "ucf",
"played_duration": 0,
"ucf_id": "579162"
},
"duration": 240,
"created_at": "2020-06-14T13:30:49.000000Z",
"updated_at": "2020-06-14T13:30:49.000000Z",
"audio_id": ""
},
{
"id": 1849311,
"uid": 19,
"bucket_id": 966,
"acr_id": "db397154fb9858f17373b5bf66be875a",
"state": 1,
"title": "Hiding my heart - Adele",
"user_defined": {
"title": "Hiding my heart",
"artist": "Adele"
},
"duration": 208,
"created_at": "2016-10-09T14:09:43.000000Z",
"updated_at": "2016-10-09T14:09:49.000000Z",
"audio_id": "12345"
}
]
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```
curl --location --request GET 'https://api-v2.acrcloud.com/api/buckets/966/files/13045360,13044049' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% endtabs %}
## Dump all the files information in this bucket (only dump bucket data once a day)
`GET` `https://api-{bucket-region}.acrcloud.com/api/buckets/:bucket_id/dump`
This is an asynchronous request. After the request is completed, you must wait and check the status through the interface. Once it becomes 1, you can download it using the down\_url address.
#### Path Parameters
| Name | Type | Description |
| -------------------------------------------- | ------ | -------------- |
| bucket\_id\* | Number | Your bucket ID |
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ------------ |
| Authorization\* | String | Bearer token |
{% tabs %}
{% tab title="200: OK " %}
```json
{
"status": 1, //when status changes to 1, the dump is ready. (default is 0)
"down_url": "https://us-api-v2.acrcloud.com/api/buckets/6556/down/sFKD2eLbGX",
//Download the file information from this URL when the status is 1
"id": 6556, //bucket ID
"name": "us-bucket", //bucket name
"task_id": "sFKD2eLbGX" //this dump task ID
}
```
{% endtab %}
{% endtabs %}
# Live Channels
## Create a live channel
`POST` `https://api-v2.acrcloud.com/api/buckets/:bucket_id/channels`
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | ------------- |
| bucket\_id | number | The bucket id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
#### Request Body
| Name | Type | Description |
| ------------- | ------ | --------------------------------------------------------------------- |
| title | string | The channel title |
| url | string | The channel URL for ingesting the fingerprint from local server |
| user\_defined | string | User-defined metadata. JSON format |
| timeshift | string | If enable the timeshifted fingerprint ingesting. 0 or 1. default is 0 |
{% tabs %}
{% tab title="201 Cake successfully retrieved." %}
```
{
"data": {
"uid": 1,
"bucket_id": 8894,
"acr_id": "b46ba66d2548b23611c6efabed035182",
"state": 0,
"title": "test",
"url": "udp://192.168.1.10",
"user_defined": {
"city": "New York"
},
"timeshift": 0,
"updated_at": "2020-12-25T05:05:17.000000Z",
"created_at": "2020-12-25T05:05:17.000000Z",
"id": 8,
"bucket_type": "Live"
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request POST 'https://api-v2.acrcloud.com/api/buckets/8894/channels' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{"title":"test", "url":"udp://192.168.1.10", "user_defined":{"city":"New York"}}'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api-v2.acrcloud.com/api/buckets/8894/channels"
payload={
"title":"test",
"url":"udp://192.168.1.10",
"user_defined":{"city":"New York"}
}
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, json=payload)
print(response.text)
```
{% endtab %}
{% endtabs %}
## List the channels
`GET` `https://api-v2.acrcloud.com/api/buckets/:bucket_id/channels`
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | ------------- |
| bucket\_id | number | The bucket id |
#### Query Parameters
| Name | Type | Description |
| --------- | ------ | ----------------------------------- |
| search | string | The title name. |
| page | string | Page number |
| per\_page | string | The results number per page. |
| | string | asc or desc. Default is desc |
| sort | string | sort by id or status. default is id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
```
{
"data": [
{
"id": 8,
"uid": 1,
"bucket_id": 8894,
"acr_id": "b46ba66d2548b23611c6efabed035182",
"channel_id": "",
"state": 1,
"title": "test",
"url": "udp://192.168.1.10",
"user_defined": {
"city": "New York"
},
"timeshift": 0,
"created_at": "2020-12-25T05:05:17.000000Z",
"updated_at": "2020-12-25T05:05:17.000000Z",
"bucket_type": "Live"
},
{
"id": 7,
"uid": 1,
"bucket_id": 8894,
"acr_id": "3482b6e845a0fed8c129108d54ed9e20",
"channel_id": "",
"state": 1,
"title": "123",
"url": "123",
"user_defined": {},
"timeshift": 1,
"created_at": "2020-09-16T03:36:59.000000Z",
"updated_at": "2020-09-16T03:36:59.000000Z",
"bucket_type": "Live"
},
{
"id": 4,
"uid": 1,
"bucket_id": 8894,
"acr_id": "f59e5c0e31a73db957b6c68fcda38c44",
"channel_id": "",
"state": 1,
"title": "channel-4",
"url": "http://127.0.0.1:123",
"user_defined": {},
"timeshift": 1,
"created_at": "2019-06-25T07:46:24.000000Z",
"updated_at": "2020-09-16T03:49:43.000000Z",
"bucket_type": "Live"
},
{
"id": 3,
"uid": 1,
"bucket_id": 8894,
"acr_id": "6cc839537aa40b2854f4e520b7d0d58b",
"channel_id": "",
"state": 1,
"title": "channel-3",
"url": "http://127.0.0.1:123",
"user_defined": {},
"timeshift": 0,
"created_at": "2019-06-25T07:46:21.000000Z",
"updated_at": "2019-11-22T11:51:57.000000Z",
"bucket_type": "Live"
}
],
"links": {
"first": "https://api-v2.acrcloud.com/api/buckets/8894/channels?page=1",
"last": "https://api-v2.acrcloud.com/api/buckets/8894/channels?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "https://api-v2.acrcloud.com/api/buckets/8894/channels",
"per_page": 20,
"to": 4,
"total": 4
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```
curl --location --request GET 'https://api-v2.acrcloud.com/api/buckets/8894/channels' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% endtabs %}
## Update a channel
`PUT` `https://api-v2.acrcloud.com/api/buckets/:bucket_id/channels/:id`
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | ----------- |
| bucket\_id | string | bucket id |
| id | string | channel id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
#### Request Body
| Name | Type | Description |
| ------------- | ------ | --------------------------------------------------------------- |
| title | string | The channel title |
| url | string | The channel URL for ingesting fingerprints on your local server |
| user\_defined | string | User-define |
| timeshift | string | If enable the timeshifted fingerprint ingestring. 0 or 1. |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"uid": 1,
"bucket_id": 8894,
"acr_id": "b46ba66d2548b23611c6efabed035182",
"state": 0,
"title": "test",
"url": "udp://192.168.1.10",
"user_defined": {
"city": "New York"
},
"timeshift": 0,
"updated_at": "2020-12-25T05:05:17.000000Z",
"created_at": "2020-12-25T05:05:17.000000Z",
"id": 8,
"bucket_type": "Live"
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request PUT 'https://api-v2.acrcloud.com/api/buckets/8884/channels/8' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{"title":"test"}'
```
{% endtab %}
{% endtabs %}
## Delete ingesting channels
`DELETE` `https://api-v2.acrcloud.com/api/buckets/:bucket_id/channels/:ids`
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | ------------------------------------- |
| bucket\_id | string | The bucket id |
| ids | string | One or multiple ids, separated by ',' |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="204 " %}
```
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request DELETE 'https://api-v2.acrcloud.com/api/buckets/8894/channels/8' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% endtabs %}
## Import channels
`POST` `https://api-v2.acrcloud.com/api/buckets/:bucket_id/rec-channels`
Import channels to LiveRec bucket.
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | ----------- |
| bucket\_id | string | Bucket id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
#### Request Body
| Name | Type | Description |
| ---- | ------ | ---------------------------------------------- |
| ids | string | One or multiple channels ids. Separated by ',' |
{% tabs %}
{% tab title="200 " %}
```
{
"data": [
{
"id": 5,
"acr_id": "a25b69e996f6f220ddb7a0c4a53a11c1",
"title": "channel-5",
"state": 0,
"bucket_id": 8885,
"original_bucket_id": 8882,
"created_at": "2020-12-25 07:39:29",
"updated_at": "2020-12-25 07:39:29",
"bucket_type": "LiveRec",
"user_defined": {}
},
{
"id": 6,
"acr_id": "08e491a33c5c1bb7418ce49254fc35ed",
"title": "adf",
"state": 0,
"bucket_id": 8885,
"original_bucket_id": 8882,
"created_at": "2020-12-25 07:39:29",
"updated_at": "2020-12-25 07:39:29",
"bucket_type": "LiveRec",
"user_defined": {
"channel_name": "abc",
"channel_type": "def"
}
}
]
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request POST 'https://api-v2.acrcloud.com/api/buckets/8885/rec-channels' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{"ids":[5,6]}'
```
{% endtab %}
{% endtabs %}
## Delete rec channels
`DELETE` `https://api-v2.acrcloud.com/api/buckets/:bucket_id/rec-channels/:ids`
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | --------------------------------------------- |
| bucket\_id | number | The bucket id |
| ids | string | One or multiple channel ids. Separated by ',' |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="204 " %}
```
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request DELETE 'https://api-v2.acrcloud.com/api/buckets/8895/rec-channels/5,6' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% endtabs %}
## Create timeshift channels
`POST` `https://api-v2.acrcloud.com/api/buckets/:bucket_id/timeshift-channels`
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | ------------- |
| bucket\_id | number | The bucket id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
#### Request Body
| Name | Type | Description |
| ---- | ------ | ----------------------------------------------------------------------------- |
| time | number | The timeshift fingerprints keep-alive time (In hours). The default is 1 hour. |
| id | number | The live channel id |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"id": 5,
"title": "channel-5",
"state": 0,
"bucket_id": 8893,
"acr_id": "a25b69e996f6f220ddb7a0c4a53a11c1",
"time": 24,
"original_bucket_id": 8882,
"created_at": "2020-12-25 07:57:52",
"updated_at": "2020-12-25 07:57:52",
"bucket_type": "LiveTimeshift",
"user_defined": {}
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request POST 'https://api-v2.acrcloud.com/api/buckets/8893/timeshift-channels' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{"id":5, "time":24}'
```
{% endtab %}
{% endtabs %}
## Delete timeshift channels
`DELETE` `https://api-v2.acrcloud.com/api/buckets/:bucket_id/timeshift-channels/:ids`
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | --------------------------------------------- |
| ids | string | One or multiple channel ids, Separated by ',' |
| bucket\_id | number | The bucket id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
## Get Live/Timeshift Channels status
`GET` `https://api-v2.acrcloud.com/api/buckets/:bucket_id/channels-stat`
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | ---------------------------- |
| bucket\_id | number | The Live/Timeshift bucket id |
#### Query Parameters
| Name | Type | Description |
| ---- | -------- | --------------------------------- |
| date | datetime | For example:
2024-05-17
|
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
#### Response
| | | |
| ------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | number | The channel id |
| title | string | The channel name |
| acr\_id | string | acr id |
| hour | string | Hour (24-hour clock) as a zero-padded decimal number. utf+0 |
| seconds | number | The fingerprint duration that the server side received.
This value has a certain margin of error (mainly due to the possibility of silence at the beginning or end of fingerprint fragments). We consider that if the total duration of fingerprints received in a complete hour is 3500 < seconds <= 3600, it indicates that the data received during this hour is normal.
|
```json
[ {
"id": 1800,
"title": "channel1",
"acr_id": "556ddb768bba7d38fa22fcb3eaf7b6ea",
"stats": {
"2024-05-17": [
{
"hour": "00",
"seconds": 3578
},
{
"hour": "01",
"seconds": 3582
},
{
"hour": "02",
"seconds": 3578
},
{
"hour": "03",
"seconds": 288
}
]
}
},
……
]
```
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location 'https://ap-api-v2.acrcloud.com/api/buckets/12334/channels-stat?date=2024-05-17' \
--header 'Authorization: Bearer YOUR_TOKEN’ \
--header 'Accept: application/json'
```
{% endtab %}
{% tab title="Python" %}
````python
```python
import requests
url = "https://api-v2.acrcloud.com/api/buckets/12334/channels-stat?date=2024-05-17"
payload = {}
headers = {
'Authorization': 'Bearer YOUR_TOKEN',
'Accept': 'application/json'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
````
{% endtab %}
{% endtabs %}
# Dedup Files
## Deduplicate the track file
`POST` `https://api-v2.acrcloud.com/api/buckets/:bucket_id/dedup-files`
Upload the fingerprints to the "DedupFile" bucket, you will get the dup files, if there are no dup files, this fingerprint will be inserted into the fingerprint database.
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | ------------- |
| bucket\_id | string | The bucket id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer Token |
#### Request Body
| Name | Type | Description |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| db\_if\_nodup | number | 0 or 1. Whether insert the fingerprint into the database if there are no duplicated tracks in the database. The default value is 1 |
| id | string | The unique track id |
| file | object | The fingerprint file |
{% tabs %}
{% tab title="200 Cake successfully retrieved." %}
```
{"data":{"dup_files": ["123"], "acr_id":"7b475aff9cf72859f65effe81e741f0e", "do_db": false}}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request POST 'https://us-api-v2.acrcloud.com/api/buckets/6556/dedup-files' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer Token' \
--form 'id="123"' \
--form 'file=@"/123.wma.db.lo"'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://us-api-v2.acrcloud.com/api/buckets/6556/dedup-files"
payload={'id': '123'}
files=[
('file',('123.wma.db.lo',open('/Users/Downloads/22494.wma.db.lo','rb'),'application/octet-stream'))
]
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer Token'
}
response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)
```
{% endtab %}
{% endtabs %}
## List all the duplicated files
`GET` `https://api-v2.acrcloud.com/api/buckets/:bucket_id/dedup-files`
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | ------------- |
| bucket\_id | string | The bucket id |
#### Query Parameters
| Name | Type | Description |
| --------- | ------ | --------------------------- |
| per\_page | number | The results number per page |
| page | number | The page number |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer Token |
{% tabs %}
{% tab title="200 " %}
```
{
"data": [
{
"dup_files": [
"8a8bfb8a",
"1a8cfd55"
],
"acr_id": "7b475aff9cf72859f65effe81e741f0e",
"created_at": "2021-02-18 09:11:23",
"updated_at": "2021-02-16 23:27:17"
}
],
"links": {
"first": "https://us-api-v2.acrcloud.com/api/buckets/123/dedup-files?page=1",
"last": "https://us-api-v2.acrcloud.com/api/buckets/123/dedup-files?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "https://us-api-v2.acrcloud.com/api/buckets/123/dedup-files",
"per_page": "20",
"to": 1,
"total": 1
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request GET 'https://us-api-v2.acrcloud.com/api/buckets/your_bucket_id/dedup-files' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer Token'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://us-api-v2.acrcloud.com/api/buckets/your_bucket_id/dedup-files"
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer Token'
}
response = requests.request("GET", url, headers=headers)
print(response.text)
```
{% endtab %}
{% endtabs %}
## Get one file's duplicated files
`GET` `https://api-v2.acrcloud.com/api/buckets/:bucket_id/dedup-files/:file_id`
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | ------------- |
| file\_id | string | The file id |
| bucket\_id | string | The bucket id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
```
{
"data": [
{
"dup_files": [
"8a8bfb8a",
"1a8cfd55"
],
"acr_id": "7b475aff9cf72859f65effe81e741f0e",
"created_at": "2021-02-18 09:11:23",
"updated_at": "2021-02-16 23:27:17"
}
]
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request GET 'https://us-api-v2.acrcloud.com/api/buckets/123/dedup-files/8a8bfb8a' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://us-api-v2.acrcloud.com/api/buckets/123/dedup-files/8a8bfb8a"
payload={}
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
{% endtab %}
{% endtabs %}
## Delete an item
`DELETE` `https://api-v2.acrcloud.com/api/buckets/:bucket_id/dedup-files/:acr_ids`
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | ----------------- |
| bucket\_id | number | The bucket id |
| acr\_ids | string | One or more acrid |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="204 " %}
```
```
{% endtab %}
{% endtabs %}
# Base Projects
## Create a project
`POST` `https://api-v2.acrcloud.com/api/base-projects`
Create a recognition project
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
#### Request Body
| Name | Type | Description |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | The project name |
| region | string | eu-west-1,us-west-2,ap-southeast-1 |
| type | string | There are three types. AVR,LCD,HR.
AVR is detecting music or custom content
LCD is detecting live channels and time-shifting channels
HR is detecting both live channel and custom contents
|
| buckets | array | The project detects content from the buckets. The format is bucket id array. |
| audio\_type | string | linein or recorded. Default is linein
recorded: Audio captured via microphone or noisy audio files
linein: Audio of original file or stream without noise
|
| external\_ids | string | spotify,deezer,isrc,upc,musicbrainz |
{% tabs %}
{% tab title="200 The project successfully created." %}
```
{
"data": {
"uid": 1,
"access_key": "e7a84ca942a13773f6d22e9fd6808fce",
"access_secret": "9zlEAx57jaCgeLpDKKQmorv0brrhAYqj076n6FyP",
"service_type": "AVR",
"state": 1,
"name": "test",
"region": "eu-west-1",
"day_limit": 0,
"total_limit": 0,
"audio_type": "linein",
"version": 1,
"external_id": "",
"updated_at": "2020-12-25T09:47:25.000000Z",
"created_at": "2020-12-25T09:47:25.000000Z",
"id": 15,
"buckets": [
{
"id": 8881,
"name": "bucket-music",
"type": "File",
"metadata_template": null
},
{
"id": 8883,
"name": "api-test",
"type": "File",
"metadata_template": null
}
],
"status_check": 2,
"external_ids": ["spotify", "isrc", "deezer"]
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request POST 'https://api-v2.acrcloud.com/api/base-projects' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{"name":"test", "region":"eu-west-1", "buckets":[8881,8883],"type":"AVR", "audio_type":"linein", "external_ids":["spotify", "isrc", "deezer"]}'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api-v2.acrcloud.com/api/base-projects"
payload={
"name":"test",
"region":"eu-west-1",
"buckets":[8881,8883],
"type":"AVR",
"audio_type":"linein",
"external_ids":["spotify", "isr\", "deezer"]
}
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, json=payload)
print(response.text)
```
{% endtab %}
{% tab title="PHP" %}
```php
'https://api-v2.acrcloud.com/api/base-projects',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{"name":"test", "region":"eu-west-1", "buckets":[8881,8883],"type":"AVR", "audio_type":"linein", "external_ids":["spotify", "isrc", "deezer"]}',
CURLOPT_HTTPHEADER => array(
'Accept: application/json',
'Authorization: Bearer token',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
```
{% endtab %}
{% tab title="Nodejs" %}
```javascript
var axios = require('axios');
var data = JSON.stringify({"name":"test","region":"eu-west-1","buckets":[8881,8883],"type":"AVR","audio_type":"linein","external_ids":["spotify","isrc","deezer"]});
var config = {
method: 'post',
url: 'https://api-v2.acrcloud.com/api/base-projects',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
},
data : data
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
```
{% endtab %}
{% endtabs %}
## List projects
`GET` `https://api-v2.acrcloud.com/api/base-projects`
#### Query Parameters
| Name | Type | Description |
| --------- | ------ | ---------------------------------- |
| region | string | eu-west-1,us-west-2,ap-southeast-1 |
| type | string | AVR,LCD,HR |
| page | string | Page number |
| per\_page | string | The results number per page |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
```
{
"data": [
{
"id": 15,
"uid": 1,
"access_key": "e7a84ca942a13773f6d22e9fd6808fce",
"access_secret": "9zlEAx57jaCgeLpDKKQmorv0brrhAYqj076n6FyP",
"name": "test",
"service_type": "AVR",
"state": 1,
"region": "eu-west-1",
"day_limit": 0,
"qps_limit": 0,
"audio_type": "linein",
"version": 1,
"external_id": "",
"created_at": "2020-12-25T09:47:25.000000Z",
"updated_at": "2020-12-25T09:47:25.000000Z",
"buckets": [
{
"id": 8881,
"name": "bucket-music",
"type": "File",
"metadata_template": null
},
{
"id": 8883,
"name": "api-test",
"type": "File",
"metadata_template": null
}
],
"status_check": 2,
"external_ids": []
},
{
"id": 14,
"uid": 1,
"access_key": "9246b72f271403f4abefd723b10d2810",
"access_secret": "TZZbedkkArX2cLDdz6PBc1rkBkUrq3izQccmjDGc",
"name": "vue-project-2",
"service_type": "AVR",
"state": 1,
"region": "ap-southeast-1",
"day_limit": 0,
"qps_limit": 0,
"audio_type": "recorded",
"version": 1,
"created_at": "2020-08-07T19:21:48.000000Z",
"updated_at": "2020-08-07T19:22:01.000000Z",
"buckets": [
{
"id": 8880,
"name": "ACRCloud Music",
"type": "ACRCloudFile",
"metadata_template": null
},
{
"id": 8881,
"name": "bucket-music",
"type": "File",
"metadata_template": null
},
{
"id": 8883,
"name": "api-test",
"type": "File",
"metadata_template": null
}
],
"status_check": 2,
"external_ids": [
"Youtube",
"Deezer"
]
},
{
"id": 13,
"uid": 1,
"access_key": "a13717e4bef752c067d0cee5dfc13dfb",
"access_secret": "W0IhtWoQjLceyRNufQUhQabudUu0009APOaciRAy",
"name": "vue-project",
"service_type": "AVR",
"state": 1,
"region": "ap-southeast-1",
"day_limit": 0,
"qps_limit": 0,
"audio_type": "recorded",
"version": 1,
"created_at": "2020-08-07T19:21:48.000000Z",
"updated_at": "2020-08-07T19:22:01.000000Z",
"buckets": [
{
"id": 8881,
"name": "bucket-music",
"type": "File",
"metadata_template": null
}
],
"status_check": 2,
"external_ids": [
"Deezer",
"Spotify"
]
},
{
"id": 5,
"uid": 1,
"access_key": "965eb1aded32934b78a599fffb9befdd",
"access_secret": "BqSmWxTV5dwJgxGVG0Pfxq1wUXHlAXBm4Poy8jpf",
"name": "param_test",
"service_type": "AVR",
"state": 1,
"region": "ap-southeast-1",
"day_limit": 0,
"qps_limit": 0,
"audio_type": "recorded",
"version": 1,
"created_at": "2020-08-07T19:21:48.000000Z",
"updated_at": "2020-08-07T19:22:01.000000Z",
"buckets": [
{
"id": 8880,
"name": "ACRCloud Music",
"type": "ACRCloudFile",
"metadata_template": null
},
{
"id": 8881,
"name": "bucket-music",
"type": "File",
"metadata_template": null
}
],
"status_check": 2,
"external_ids": [
"deezer",
"itunes",
"spotify",
"youtube",
"isrc",
"upc",
"musicstory",
"lyricfind"
]
},
{
"id": 3,
"uid": 1,
"access_key": "01d97da894699fb8e0ea9832e679fdc8",
"access_secret": "0t7zQ23F2yhaXEBqUMZ6qvRzhiGt8BKMvk6FPkfG",
"name": "hr",
"service_type": "HR",
"state": 1,
"region": "ap-southeast-1",
"day_limit": 0,
"qps_limit": 0,
"audio_type": "recorded",
"version": 1,
"external_id": "",
"created_at": "2020-08-07T19:21:48.000000Z",
"updated_at": "2020-08-07T19:22:01.000000Z",
"buckets": [
{
"id": 8881,
"name": "bucket-music",
"type": "File",
"metadata_template": null
},
{
"id": 8882,
"name": "tv",
"type": "Live",
"metadata_template": null
}
],
"status_check": 2,
"external_ids": []
},
{
"id": 2,
"uid": 1,
"access_key": "896cf772dc1b5f2e9287f524fcc78971",
"access_secret": "5TETNWSHDnGbXv6OhVrgkbbVzQtuhMuFSDpXu4TW",
"name": "tv_project",
"service_type": "LCD",
"state": 1,
"region": "ap-southeast-1",
"day_limit": 0,
"qps_limit": 0,
"audio_type": "recorded",
"version": 1,
"external_id": "",
"created_at": "2020-08-07T19:21:48.000000Z",
"updated_at": "2020-08-07T19:22:01.000000Z",
"buckets": [
{
"id": 8882,
"name": "tv",
"type": "Live",
"metadata_template": null
}
],
"status_check": 2,
"external_ids": []
}
],
"links": {
"first": "https://api-v2.acrcloud.com/api/base-projects?page=1",
"last": "https://api-v2.acrcloud.com/api/base-projects?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "https://api-v2.acrcloud.com/api/base-projects",
"per_page": "20",
"to": 6,
"total": 6
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/base-projects?type=AVR' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% endtabs %}
## Get a project
`GET` `https://api-v2.acrcloud.com/api/base-projects/:id`
Get the details of a project
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------- |
| id | number | The project id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"uid": 1,
"access_key": "e7a84ca942a13773f6d22e9fd6808fce",
"access_secret": "9zlEAx57jaCgeLpDKKQmorv0brrhAYqj076n6FyP",
"service_type": "AVR",
"state": 1,
"name": "test",
"region": "eu-west-1",
"day_limit": 0,
"total_limit": 0,
"audio_type": "linein",
"version": 1,
"external_id": "",
"updated_at": "2020-12-25T09:47:25.000000Z",
"created_at": "2020-12-25T09:47:25.000000Z",
"id": 15,
"buckets": [
{
"id": 8881,
"name": "bucket-music",
"type": "File",
"metadata_template": null
},
{
"id": 8883,
"name": "api-test",
"type": "File",
"metadata_template": null
}
],
"status_check": 2,
"external_ids": ["spotify", "isrc", "deezer"]
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request GET 'http://127.0.0.1:8080/api/base-projects/15' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% endtabs %}
## Update a project
`PUT` `https://api-v2.acrcloud.com/api/base-projects/:id`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------- |
| id | number | The project id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
#### Request Body
| Name | Type | Description |
| ------------- | ------ | ------------------------------------------------------------------------ |
| name | string | Project name |
| buckets | array | The project detects content from buckets. The format is bucket id array. |
| audio\_type | string | linein or recorded |
| external\_ids | string | spotify,deezer,youtube,isrc,upc,musicbrainz |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"uid": 1,
"access_key": "e7a84ca942a13773f6d22e9fd6808fce",
"access_secret": "9zlEAx57jaCgeLpDKKQmorv0brrhAYqj076n6FyP",
"service_type": "AVR",
"state": 1,
"name": "test",
"region": "eu-west-1",
"day_limit": 0,
"total_limit": 0,
"audio_type": "linein",
"version": 1,
"external_id": "",
"updated_at": "2020-12-25T09:47:25.000000Z",
"created_at": "2020-12-25T09:47:25.000000Z",
"id": 15,
"buckets": [
{
"id": 8881,
"name": "bucket-music",
"type": "File",
"metadata_template": null
},
{
"id": 8883,
"name": "api-test",
"type": "File",
"metadata_template": null
}
],
"status_check": 2,
"external_ids": ["spotify", "isrc", "deezer"]
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request PUT 'http://127.0.0.1:8080/api/base-projects/15' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{"name":"test", "region":"eu-west-1", "buckets":[8881,8883],"type":"AVR", "audio_type":"linein", "external_ids":["spotify", "isrc", "deezer"]}'
```
{% endtab %}
{% endtabs %}
## Delete a project
`DELETE` `https://api-v2.acrcloud.com/api/base-projects/:id`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------- |
| id | number | The project id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="204 " %}
```
```
{% endtab %}
{% endtabs %}
## Get the status of the project's buckets
`GET` `https://us-api-v2.acrcloud.com/api/base-projects/:id/buckets-status`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------- |
| id | string | The project id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
Response
| Nmae | Type | Description |
| ------- | ------ | ----------------------------------- |
| buckets | string | The buckets your porject are using. |
| nodes | string | The server nodes for the buckets |
| status | string | 1: healthy
0: unhealthy
|
{% tabs %}
{% tab title="200 " %}
````
```json
{
"ACRCloudFile": [
{
"buckets": [
{
"name": "ACRCloud Music",
"id": 23
}
],
"nodes": {
"node": "46671216359c47fc0c1b236194f7cca0",
"status": 1
}
}
]
}
```
````
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```
curl --location --request GET 'https://us-api-v2.acrcloud.com/api/base-projects/:your_project_id/buckets-status' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer your_token'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://us-api-v2.acrcloud.com/api/base-projects/:project_id/buckets-status"
payload={}
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer your_token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
{% endtab %}
{% endtabs %}
## Get the statistics of the project
`GET` `https://api-v2.acrcloud.com/api/base-projects/:id/day-stat`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------- |
| id | number | The project id |
#### Query Parameters
| Name | Type | Description |
| ----- | ------ | ------------------------- |
| start | string | The start date YYYY-MM-DD |
| end | string | The end date |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```
curl --request GET 'https://api-v2.acrcloud.com/api/base-projects/:id/day-stat?start=2021-04-09&end=2021-04-23'
--header 'Accept: application/json' \
--header 'Authorization: Bearer your_token'
```
{% endtab %}
{% endtabs %}
# OfflineDBs
## Create an offline db
`POST` `https://api-v2.acrcloud.com/api/offlinedbs`
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
#### Request Body
| Name | Type | Description |
| ----------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | The offline db name |
| region | string | us-west-2,eu-west-1,ap-southeast-1 |
| buckets | array | The bucket id array |
| audio\_type | string | linein or recorded. It's the type of audios you want to recognize.
linein: Audio of the original files without noise.
recorded: Audio captured via microphone or noisy audio files
|
{% tabs %}
{% tab title="200 Cake successfully retrieved." %}
```
```
{% endtab %}
{% endtabs %}
## Rebuild the offline db
`PUT` `https://api-v2.acrcloud.com/api/offlinedbs/:id`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------------- |
| id | number | The offline db id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
## Delete the offline db
`DELETE` `https://api-v2.acrcloud.com/api/offlinedbs/:id`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ---------------- |
| id | string | The offlinedb id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="204 " %}
```
```
{% endtab %}
{% endtabs %}
## Download the offlinedb
`GET` `https://api-v2.acrcloud.com/api/offlinedbs/:id`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ---------------- |
| id | string | The offlinedb id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
# BM Projects
# Custom Streams Projects
## Create Custom Streams Project
`POST` `https://api-v2.acrcloud.com/api/bm-cs-projects`
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
| Content-Type | string | application/json |
#### Request Body
| Name | Type | Description |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| external\_ids | string | spotify,deezer,isrc,upc,musicbrainz |
| metadata\_template | string | The streams metadata template |
| region | string | eu-west-1,us-west-2,ap-southeast-1 |
| name | string | Project name |
| buckets | string | Bucket ids array |
| type | string | BM-ACRC or BM-LOCAL
BM-ACRC: Ingesting the streams audio data on our server.
BM-LOCAL: ingesting the streams audio data on your local server. Please refer to Local monitoring Tool
|
{% tabs %}
{% tab title="201 " %}
```
{
"data":{
"uid":1,
"access_key":"************",
"type":"BM-ACRC",
"state":1,
"name":"bm-test",
"region":"ap-southeast-1",
"bucket_group":"8881",
"external_id":"",
"updated_at":"2021-01-04 10:42:24",
"created_at":"2021-01-04 10:42:24",
"id":13528,
"buckets":[
{
"id":8881,
"uid":1,
"name":"bucket-music",
"type":"File",
"node":"127.0.0.1-871",
"state":1,
"region":"ap-southeast-1",
"metadata_template":"{"artist":{"default":"abc"}, "album":{
"type":"select", "default":"334", "options":["123", "334"]}}",
"labels":[
"Music",
"Video"
],
"net_type":1,
"created_at":"2019-03-01 15:31:25",
"updated_at":"2020-12-24 08:26:35",
"num":1,
"size":"300000",
"access_permission":"private"
}
],
"status_check":2,
"external_ids":[
"spotify","deezer","isrc"
],
"metadata_template":"StreamId,City,FM",
"monitoring_num":0
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request POST 'https://api-v2.acrcloud.com/api/bm-cs-projects' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}' \
--header 'Content-Type: application/json' \
--data-raw '{"name":"test", "region":"eu-west-1", "buckets":[8881,8883],"type":"BM-ACRC", "external_ids":["spotify", "isrc", "deezer"]}'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api-v2.acrcloud.com/api/bm-cs-projects"
payload = {
"name": "test",
"region": "eu-west-1",
"buckets": [
8881,
8883
],
"type": "BM-ACRC",
"external_ids": [
"spotify",
"isrc",
"deezer"
]
}
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your token}',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, json=payload)
print(response.text)
```
{% endtab %}
{% endtabs %}
## List the projects
`GET` `https://api-v2.acrcloud.com/api/bm-cs-projects`
#### Query Parameters
| Name | Type | Description |
| --------- | ------ | ----------- |
| page | string | |
| region | string | |
| types | string | |
| per\_page | string | |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Accept | string | application/json |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
```
{
"data":[
{
"id":12345,
"name":"test",
"uid":1,
"type":"BM-ACRC",
"region":"ap-southeast-1",
"state":1,
"access_key":"************",
"bucket_group":"8891,8880",
"external_id":"",
"noise":1,
"created_at":"2020-07-20 15:56:21",
"updated_at":"2020-07-21 03:43:01",
"buckets":[
{
"id":8891,
"uid":1,
"name":"vue-bucket",
"type":"File",
"node":"127.0.0.1-871",
"state":1,
"region":"ap-southeast-1",
"metadata_template":"album",
"labels":[
"Music",
"Video"
],
"net_type":1,
"created_at":"2019-07-30 09:02:43",
"updated_at":"2019-08-16 07:17:32",
"num":2,
"size":"600",
"access_permission":"private",
"access_users":[
"olym.yin@gmail.com"
]
},
{
"id":8880,
"uid":0,
"name":"ACRCloud Music",
"type":"ACRCloudFile",
"node":"127.0.0.1-890",
"state":1,
"region":"ap-southeast-1",
"metadata_template":"",
"labels":[
"Music"
],
"net_type":1,
"created_at":"2019-03-01 15:31:25",
"updated_at":"-0001-11-30 00:00:00",
"num":10000,
"size":10000,
"access_permission":"private"
}
],
"status_check":2,
"external_ids":[
],
"metadata_template":"city,country",
"monitoring_num":0
}
],
"links":{
"first":"https://api-v2.acrcloud.com/api/bm-cs-projects?page=1",
"last":"https://api-v2.acrcloud.com/api/bm-cs-projects?page=1",
"prev":null,
"next":null
},
"meta":{
"current_page":1,
"from":1,
"last_page":1,
"path":"https://api-v2.acrcloud.com/api/bm-cs-projects",
"per_page":"20",
"to":1,
"total":1
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/bm-cs-projects' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}'
```
{% endtab %}
{% endtabs %}
## Update a project
`PUT` `https://api-v2.acrcloud.com/api/bm-cs-projects/:id`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------- |
| id | number | The project id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Accept | string | application/json |
| Authorization | string | Bearer token |
#### Request Body
| Name | Type | Description |
| ------------------ | ------ | ----------- |
| name | string | |
| buckets | string | |
| external\_ids | string | |
| metadata\_template | string | |
{% tabs %}
{% tab title="200 " %}
```
{
"data":{
"uid":1,
"access_key":"**************",
"type":"BM-ACRC",
"state":1,
"name":"bm-test",
"region":"ap-southeast-1",
"bucket_group":"8881",
"external_id":"",
"updated_at":"2021-01-04 10:42:24",
"created_at":"2021-01-04 10:42:24",
"id":13528,
"buckets":[
{
"id":8881,
"uid":1,
"name":"bucket-music",
"type":"File",
"node":"127.0.0.1-871",
"state":1,
"region":"ap-southeast-1",
"metadata_template":"{"artist":{"default":"abc"}, "album":{
"type":"select", "default":"334", "options":["123", "334"]}}",
"labels":[
"Music",
"Video"
],
"net_type":1,
"created_at":"2019-03-01 15:31:25",
"updated_at":"2020-12-24 08:26:35",
"num":1,
"size":"300000",
"access_permission":"private"
}
],
"status_check":2,
"external_ids":[
"spotify","deezer","isrc"
],
"metadata_template":"StreamId,City,FM",
"monitoring_num":0
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Python" %}
```python
import requests
import json
url = "http://127.0.0.1:8080/api/bm-cs-projects/13528"
payload = json.dumps({
"name": "test",
"buckets": [
8881,
8883
],
"external_ids": [
"spotify",
"isrc",
"deezer"
]
})
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.request("PUT", url, headers=headers, data=payload)
print(response.text)
```
{% endtab %}
{% endtabs %}
## Delete a project
`DELETE` `https://api-v2.acrcloud.com/api/bm-cs-projects/:id`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------- |
| id | number | The project id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="204 " %}
```
```
{% endtab %}
{% endtabs %}
## Set result callback url
`POST` `https://api-v2.acrcloud.com/api/bm-cs-projects/:id/result-callback`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------- |
| id | number | The project id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
| Content-Type | string | application/json |
#### Request Body
| Name | Type | Description |
| --------------------- | ------ | ----------- |
| result\_callback\_url | string | |
{% tabs %}
{% tab title="200 " %}
```
{
"data":{
"id":13528,
"name":"bm-test",
"uid":1,
"type":"BM-ACRC",
"region":"ap-southeast-1",
"state":1,
"access_key":"***********",
"bucket_group":"8881",
"external_id":"",
"noise":1,
"created_at":"2021-01-04 10:42:24",
"updated_at":"2021-01-04 10:42:24",
"buckets":[
{
"id":8881,
"uid":1,
"name":"bucket-music",
"type":"File",
"node":"127.0.0.1-871",
"state":1,
"region":"ap-southeast-1",
"metadata_template":"{"artist":{"default":"abc"}, "album":{
"type":"select", "default":"334", "options":["123", "334"]}}",
"labels":[
"Music",
"Video"
],
"net_type":1,
"created_at":"2019-03-01 15:31:25",
"updated_at":"2020-12-24 08:26:35",
"num":1,
"size":"300000",
"access_permission":"private"
}
],
"status_check":2,
"external_ids":[
],
"metadata_template":"StreamId,City,FM",
"result_callback_url":"https://callback.acrcloud.com",
"result_callback_send_type":"JSON",
"result_callback_send_noresult":"NO",
"result_callback_retry":0,
"monitoring_num":0
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="CURL" %}
```bash
curl --location --request POST 'https://api-v2.acrcloud.com/api/bm-cs-projects/12345/result-callback' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}' \
--header 'Content-Type: application/json' \
--data-raw '{"result_callback_url":"{your callback URL}"}'
```
{% endtab %}
{% endtabs %}
> The following is the example of the results of the monitoring system posting to your results callback URL
{% tabs %}
{% tab title="Sample result of Music(Callback)" %}
```
{
"stream_url": "xxxx",
"stream_id": "s-Ixxxxd",
"status": 1,
"data": {
"status": {
"msg": "Success",
"version": "1.0",
"code": 0
},
"result_type": 0,
"metadata": {
"music": [{
"album": {
"name": "Creedence Clearwater Revival - Best Of"
},
"play_offset_ms": 75500,
"sample_begin_time_offset_ms": 6440,
"title": "Proud Mary",
"result_from": 3,
"release_date": "2008-01-01",
"sample_end_time_offset_ms": 9420,
"genres": [{
"name": "Country"
}, {
"name": "Pop"
}, {
"name": "Rock"
}, {
"name": "Rock & Roll/Rockabilly"
}],
"label": "Universal Music",
"duration_ms": 186506,
"score": 100.0,
"db_begin_time_offset_ms": 72200,
"artists": [{
"name": "Creedence Clearwater Revival"
}],
"db_end_time_offset_ms": 75180,
"external_ids": {
"isrc": "USFI86900049",
"upc": "888072308701"
},
"acrid": "463aeeb5840215833abe6bf7b02304f6",
"external_metadata": {
"spotify": {
"track": {
"name": "Proud Mary",
"id": "5Op2Ra4kgzlTpEmD9NUanY"
},
"album": {
"name": "Creedence Clearwater Revival - Best Of"
},
"artists": [{
"name": "Creedence Clearwater Revival"
}]
},
"lyricfind": {
"lfid": "001-1188346"
},
"youtube": {
"vid": "5hid10EgMXE"
},
"musicstory": {
"track": {
"id": "9258633"
},
"album": {
"id": "677371"
},
"release": {
"id": "1640721"
}
},
"musicbrainz": {
"track": {
"id": "1632ee2b-4f4b-42eb-909f-8279e66dc1ce"
}
},
"deezer": {
"track": {
"name": "Proud Mary",
"id": "883642"
},
"album": {
"name": "Creedence Clearwater Revival - Best Of"
},
"artists": [{
"name": "Creedence Clearwater Revival"
}]
}
}
}],
"timestamp_utc": "2022-02-22 12:19:28",
"played_duration": 173,
"type": "delay"
}
}
}
```
{% endtab %}
{% endtabs %}
## Set state notification callback
`POST` `https://api-v2.acrcloud.com/api/bm-cs-projects/:id/state-notification`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------- |
| id | string | The project id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
| Content-Type | string | application/json |
#### Request Body
| Name | Type | Description |
| ------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| state\_notification\_email | string | state\_notification\_email: if the streams' states change, we will send a notification to the email you set. |
| state\_notification\_email\_frequency | string | state\_notification\_email\_frequency:
0:High
1:Low
2:None
|
| state\_notification\_url | string | state\_notification\_url: if the streams' states change, we will post a request to this url you set. |
{% tabs %}
{% tab title="200 " %}
```
{
"data":{
"id":13528,
"name":"bm-test",
"uid":1,
"type":"BM-ACRC",
"region":"ap-southeast-1",
"state":1,
"access_key":"***************",
"bucket_group":"8881",
"external_id":"",
"noise":1,
"created_at":"2021-01-04 10:42:24",
"updated_at":"2021-01-04 10:42:24",
"buckets":[
{
"id":8881,
"uid":1,
"name":"bucket-music",
"type":"File",
"node":"127.0.0.1-871",
"state":1,
"region":"ap-southeast-1",
"metadata_template":"{"artist":{"default":"abc"}, "album":{
"type":"select", "default":"334", "options":["123", "334"]}}",
"labels":[
"Music",
"Video"
],
"net_type":1,
"created_at":"2019-03-01 15:31:25",
"updated_at":"2020-12-24 08:26:35",
"num":1,
"size":"300000",
"access_permission":"private"
}
],
"status_check":2,
"external_ids":[
],
"metadata_template":"StreamId,City,FM",
"result_callback_url":"https://callback.acrcloud.com",
"result_callback_send_type":"JSON",
"result_callback_send_noresult":"NO",
"result_callback_retry":0,
"state_notification_url":"http://test.notification.com",
"state_notification_email":"olym@acrcloud.com",
"state_notification_email_frequency":"LOW",
"monitoring_num":2
}
}
```
{% endtab %}
{% endtabs %}
# Streams
## Add a stream
`POST` `https://api-v2.acrcloud.com/api/bm-cs-projects/:pid/streams`
#### Path Parameters
| Name | Type | Description |
| ------------------------------------- | ------ | ----------- |
| pid\* | string | Project Id. |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
| Content-Type | string | application/json |
#### Request Body
| Name | Type | Description |
| ---------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------- |
| stream\_urls\* | array | |
| name\* | string | |
| config\_id\* | integer | Please see the config list [here](https://console.acrcloud.com/bm/?region=eu-west-1#/custom-configs) |
| user\_defined | string | User-defined stream metadata |
{% tabs %}
{% tab title="201 Cake successfully retrieved." %}
```
{
"data":
{
"stream_id":"s-AO****",
"uid":19,
"mcp_id":12417,
"stream_type":"Audio",
"name":"asdfasdf",
"state":"Running",
"code":0,
"stream_urls":[
"http://*******"
],
"current_url":"http://*******",
"region":"eu-west-1",
"user_defined":null,
"pitch_shift":0,
"check_pitch_shift":0,
"remark":"",
"created_at":"2020-06-07 07:42:16",
"updated_at":"2021-01-04 10:06:37",
"record_video":0,
"stream_rec_type":0,
"epg":"",
"config":{
"id":1,
"name":"non-realtime for music",
"uid":0,
"rec_length":10,
"interval":0,
"rec_timeout":5,
"monitor_timeout":25,
"noise":1,
"delay":1,
"record":{
"record":0,
"record_after":8,
"record_before":5
},
"created_at":"2018-05-31T03:20:53.000000Z"
},
"timemap":0,
"ucf":0
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request POST 'https://api-v2.acrcloud.com/api/bm-cs-projects/{your_project_id}/streams' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}' \
--header 'Content-Type: application/json' \
--data-raw '{"stream_urls":["https://streamurl.com/1234"],"name":"test","config_id":3, "user_defined":{"country":"France"}}'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api-v2.acrcloud.com/api/bm-cs-projects/{your_project_id}/streams"
payload = {
"stream_urls": [
"https://streamurl.com/1234"
],
"name": "test",
"config_id": 3,
"user_defined": {"country": "France"}
}
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your token}',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, json=payload)
print(response.text)
```
{% endtab %}
{% endtabs %}
## List streams in a project
`GET` `https://api-v2.acrcloud.com/api/bm-cs-projects/:pid/streams`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------- |
| pid | string | The Project ID |
#### Query Parameters
| Name | Type | Description |
| ------------- | ------ | --------------------------------------------------------------------- |
| timemap | number | 0 or 1 |
| state | string | All,Running,Timeout,Paused,Invalid URL,Mute,Other. Default is All. |
| search\_value | string | Search by Name, StreamID, URL, User-defind, Remark |
| sort | string | sort by 'created\_at', 'stream\_id', 'name', Default is 'created\_at' |
| order | string | order by desc or asc, default is desc. |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
{% tabs %}
{% tab title="200 " %}
```
{
"data": [
{
"stream_id": "s-At*****",
"uid": 19,
"mcp_id": 12417,
"stream_type": "Audio",
"name": "test",
"state": "Running",
"code": 0,
"stream_urls": [
"http://*******"
],
"current_url": "http://*******",
"region": "eu-west-1",
"user_defined": null,
"pitch_shift": 0,
"check_pitch_shift": 0,
"remark": "",
"created_at": "2019-09-19 09:59:17",
"updated_at": "2021-02-21 23:03:04",
"record_video": 0,
"stream_rec_type": 0,
"epg": "",
"config": {
"id": 15,
"name": "non-realtime and recording stream",
"uid": 72,
"rec_length": 10,
"interval": 0,
"rec_timeout": 5,
"monitor_timeout": 25,
"noise": 1,
"delay": 1,
"record": {
"record": 10,
"record_after": 0,
"record_before": 0
},
"created_at": "2018-07-26T03:19:15.000000Z"
},
"timemap": 1,
"ucf": 0
}
],
"links": {
"first": "https://api-v2.acrcloud.com/api/bm-cs-projects/12848/streams?page=1",
"last": "https://api-v2.acrcloud.com/api/bm-cs-projects/12848/streams?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "https://api-v2.acrcloud.com/api/bm-cs-projects/12848/streams",
"per_page": 50,
"to": 1,
"total": 1
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/bm-cs-projects/13528/streams' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}'
```
{% endtab %}
{% endtabs %}
## Update a stream
`PUT` `https://api-v2.acrcloud.com/api/bm-cs-projects/:pid/streams/:stream_id`
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | -------------- |
| pid | number | The project id |
| stream\_id | string | The stream id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
| Content-type | string | application/json |
#### Request Body
| Name | Type | Description |
| ------------- | ------ | ------------------------------------- |
| name | string | The stream name |
| stream\_urls | array | The stream urls |
| config\_id | number | The config id |
| user\_defined | object | User-defined metadata for this stream |
{% tabs %}
{% tab title="200 " %}
```
{
"data":
{
"stream_id":"s-At*****",
"uid":19,
"mcp_id":12417,
"stream_type":"Audio",
"name":"test2",
"state":"Running",
"code":0,
"stream_urls":[
"https://*******"
],
"current_url":"https://*******",
"region":"eu-west-1",
"user_defined":null,
"pitch_shift":0,
"check_pitch_shift":0,
"remark":"",
"created_at":"2020-06-07 07:42:16",
"updated_at":"2021-01-04 10:06:37",
"record_video":0,
"stream_rec_type":0,
"epg":"",
"config":{
"id":1,
"name":"non-realtime for music",
"uid":0,
"rec_length":10,
"interval":0,
"rec_timeout":5,
"monitor_timeout":25,
"noise":1,
"delay":1,
"record":{
"record":0,
"record_after":8,
"record_before":5
},
"created_at":"2018-05-31T03:20:53.000000Z"
},
"timemap":0,
"ucf":0
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request PUT 'https://api-v2.acrcloud.com/api/bm-cs-projects/13528/streams/s-0xAHfNh' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}' \
--header 'Content-Type: application/json' \
--data-raw '{"stream_urls":["https://streamurl.com/1234"],"name":"test2","config_id":1}'
```
{% endtab %}
{% endtabs %}
## Delete a stream
`DELETE` `https://api-v2.acrcloud.com/api/bm-cs-projects/:pid/streams/:stream_ids`
#### Path Parameters
| Name | Type | Description |
| ----------- | ------ | ------------------------------------- |
| pid | number | The project id |
| stream\_ids | string | Multiple stream ids, separated by "," |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
{% tabs %}
{% tab title="204 " %}
```
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request DELETE 'https://api-v2.acrcloud.com/api/bm-cs-projects/13528/streams/s-rHmM7rc' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}'
```
{% endtab %}
{% endtabs %}
## Pause a stream
`PUT` `https://api-v2.acrcloud.com/api/bm-cs-projects/:pid/streams/:stream_ids/pause`
#### Path Parameters
| Name | Type | Description |
| ----------- | ------ | -------------------------------------------- |
| pid | number | |
| stream\_ids | string | One or multiple stream ids, separated by ',' |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
## Restart a stream
`PUT` `https://api-v2.acrcloud.com/api/bm-cs-projects/:pid/streams/:stream_ids/restart`
#### Path Parameters
| Name | Type | Description |
| ----------- | ------ | -------------------------------------------- |
| pid | string | |
| stream\_ids | string | One or multiple stream ids, separated by ',' |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
# Streams Results
## Get the stream monitoring results
`GET` `https://api-v2.acrcloud.com/api/bm-cs-projects/:pid/streams/:stream_id/results`
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | ------------------------------------------ |
| pid | number | The project id |
| stream\_id | string | ID of the cake to get, for free of course. |
#### Query Parameters
| Name | Type | Description |
| --------------------- | ------ | --------------------------------------------------------------------------------------------------------------------- |
| type | string | last: get the last results
day: get the day results
Default is day
|
| date | string | Get all the results on this date. The format is YYYYmmdd (E.g. 20210201) |
| min\_duration | number | Only return the results of played\_duration greater than or equal to min\_duration seconds (default: 0) |
| max\_duration | number | Only return the results of played\_duration less than or equal to max\_duration seconds (default: 3600) |
| isrc\_country | string | Only return results that match the isrc country code (E.g. DE, FR, IT, US) |
| with\_false\_positive | number | 0: does not return results marked as false positive. (Default)
1: returns results marked false positive.
|
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
{% tabs %}
{% tab title="200 " %}
```
{
"data": [
{
"status": {
"msg": "Success",
"code": 0,
"version": "1.0"
},
"result_type": 0,
"metadata": {
"type": "delay",
"timestamp_utc": "2021-01-07 10:18:45",
"played_duration": 232,
"music": [
{
"album": {
"name": "Angkara"
},
"play_offset_ms": 4780,
"sample_begin_time_offset_ms": 4940,
"title": "Angkara",
"result_from": 3,
"release_date": "2020-07-18",
"sample_end_time_offset_ms": 9580,
"label": "SEVENTEEN ELEVEN MUSIC SDN BHD",
"duration_ms": 240780,
"score": 100,
"db_begin_time_offset_ms": 0,
"artists": [
{
"name": "Siti Nordiana"
}
],
"db_end_time_offset_ms": 4640,
"external_ids": {},
"acrid": "65e0152da24e3a79935c296ca1c541bf",
"external_metadata": {}
}
]
}
}
]
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl #day" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/bm-cs-projects/12417/streams/s-0xAHfNh/results?type=day&date=20210201' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% tab title="Curl #last" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/bm-cs-projects/12417/streams/s-0xAHfNh/results?type=last' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}'
```
{% endtab %}
{% endtabs %}
#### The following is a sample script that displays the results in real-time
```
[
"method" => "GET",
"header" => "Accept: application/json\r\n" .
"Authorization: Bearer " . $token . "\r\n"
]
];
$context = stream_context_create($opts);
$data = file_get_contents("https://api-v2.acrcloud.com/api/bm-cs-projects/" . $project_id . "/streams/" . $stream_id . "/results?type=last", false, $context);
$obj = json_decode($data, true);
# var_dump($obj);
$title = "";
$artists = "";
if (isset($obj['data']) && count($obj['data']) > 0) {
$metadata = $obj['data'][0]['metadata'];
if (array_key_exists('music', $metadata)) {
$music = $metadata['music'][0];
$title = $music['title'];
$arlist = [];
if (array_key_exists('artists', $music)) {
foreach($music['artists'] as $ar) {
$arlist[] = $ar['name'];
}
}
if (count($arlist) > 0) {
$artists = implode(', ', $arlist);
}
}
}
$ret = ['title'=>$title, 'artists'=>$artists, 'result'=>$obj];
print_r(json_encode($ret));
?>
```
## Getting results not recognized but detected as music. (Note: This API is only available for streams with music detection enabled)
`GET` `https://api-v2.acrcloud.com/api/bm-cs-projects/:pid/streams/:stream_id/unknown_results`
#### Path Parameters
| Name | Type | Description |
| -------------------------------------------- | ------ | -------------- |
| pid\* | number | The project id |
| stream\_id\* | string | stream\_id |
#### Query Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------- |
| date\* | string | Get all the results on this date. The format is YYYYmmdd (E.g. 20210201) |
| min\_duration | number | Only return the results of played\_duration greater than or equal to min\_duration seconds (default: 0) |
| max\_duration | number | Only return the results of played\_duration less than or equal to max\_duration seconds (default: 3600) |
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization\* | string | Bearer token |
| Accept | string | application/json |
{% tabs %}
{% tab title="200: OK " %}
```json
{
"data": [
{
"start_timestamp_utc": "2023-10-18 00:11:02",
"end_timestamp_utc": "2023-10-18 00:12:05",
"played_duration": 63,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 00:20:06",
"end_timestamp_utc": "2023-10-18 00:21:24",
"played_duration": 78,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 00:36:12",
"end_timestamp_utc": "2023-10-18 00:37:13",
"played_duration": 61,
"name": "Foreground music"
},
{
"start_timestamp_utc": "2023-10-18 00:58:54",
"end_timestamp_utc": "2023-10-18 00:59:57",
"played_duration": 63,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 01:04:28",
"end_timestamp_utc": "2023-10-18 01:05:35",
"played_duration": 67,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 02:38:06",
"end_timestamp_utc": "2023-10-18 02:39:16",
"played_duration": 70,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 03:20:48",
"end_timestamp_utc": "2023-10-18 03:22:04",
"played_duration": 76,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 05:29:10",
"end_timestamp_utc": "2023-10-18 05:30:18",
"played_duration": 68,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 07:21:34",
"end_timestamp_utc": "2023-10-18 07:22:51",
"played_duration": 77,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 08:18:52",
"end_timestamp_utc": "2023-10-18 08:20:08",
"played_duration": 76,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 08:41:13",
"end_timestamp_utc": "2023-10-18 08:42:20",
"played_duration": 67,
"name": "Foreground music"
},
{
"start_timestamp_utc": "2023-10-18 08:42:30",
"end_timestamp_utc": "2023-10-18 08:43:37",
"played_duration": 67,
"name": "Foreground music"
},
{
"start_timestamp_utc": "2023-10-18 09:24:51",
"end_timestamp_utc": "2023-10-18 09:26:01",
"played_duration": 70,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 09:43:02",
"end_timestamp_utc": "2023-10-18 09:44:06",
"played_duration": 64,
"name": "Foreground music"
},
{
"start_timestamp_utc": "2023-10-18 11:24:38",
"end_timestamp_utc": "2023-10-18 11:25:48",
"played_duration": 70,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 12:03:12",
"end_timestamp_utc": "2023-10-18 12:04:15",
"played_duration": 63,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 12:14:14",
"end_timestamp_utc": "2023-10-18 12:15:17",
"played_duration": 63,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 12:19:33",
"end_timestamp_utc": "2023-10-18 12:20:47",
"played_duration": 74,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 12:28:30",
"end_timestamp_utc": "2023-10-18 12:29:50",
"played_duration": 80,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 12:53:57",
"end_timestamp_utc": "2023-10-18 12:55:15",
"played_duration": 78,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 14:01:51",
"end_timestamp_utc": "2023-10-18 14:02:54",
"played_duration": 63,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 14:58:57",
"end_timestamp_utc": "2023-10-18 14:59:59",
"played_duration": 62,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 15:38:38",
"end_timestamp_utc": "2023-10-18 15:39:43",
"played_duration": 65,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 17:01:36",
"end_timestamp_utc": "2023-10-18 17:02:39",
"played_duration": 63,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 17:23:08",
"end_timestamp_utc": "2023-10-18 17:24:08",
"played_duration": 60,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 18:01:47",
"end_timestamp_utc": "2023-10-18 18:02:50",
"played_duration": 63,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 18:55:37",
"end_timestamp_utc": "2023-10-18 18:56:44",
"played_duration": 67,
"name": "Foreground music"
},
{
"start_timestamp_utc": "2023-10-18 21:41:16",
"end_timestamp_utc": "2023-10-18 21:42:26",
"played_duration": 70,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-10-18 22:02:03",
"end_timestamp_utc": "2023-10-18 22:03:13",
"played_duration": 70,
"name": "Background music"
}
]
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```
curl --location 'https://api-v2.acrcloud.com/api/bm-cs-projects/1234/streams/s-xxxxx/unknown_results?date=20231018&min_duration=60&max_duration=80' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% endtabs %}
# Streams State
## Get the state of the stream
`GET` `https://api-v2.acrcloud.com/api/bm-cs-projects/:pid/streams/:stream_id/state`
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | -------------- |
| pid | number | The project id |
| stream\_id | string | The stream id |
#### Query Parameters
| Name | Type | Description |
| ----------- | ------- | --------------------------------------------------------------------------------------------------------- |
| timeoffset | integer | Time offset from UTC(e.g: The timeoffset of Tokyo(UTC+9) is -540, the timeoffset of Dubai(UTC+4) is -240) |
| start\_date | string | Start date(YYYYmmdd, e.g: 20210301) |
| end\_date | string | End date(YYYYmmdd, e.g: 20210302) |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"total_time": 318895,
"valid_time": 312323,
"timeoffset": -480,
"state_list": [
{
"code": 0,
"start": "2021-03-26 00:00:00",
"end": "2021-03-26 00:06:38",
"duration": 398
},
{
"code": 12,
"start": "2021-03-26 00:06:38",
"end": "2021-03-26 00:10:58",
"duration": 260
},
{
"code": 0,
"start": "2021-03-26 00:10:58",
"end": "2021-03-26 00:19:40",
"duration": 522
},
{
"code": 12,
"start": "2021-03-26 00:19:40",
"end": "2021-03-26 00:21:10",
"duration": 90
},
{
"code": 0,
"start": "2021-03-26 00:21:10",
"end": "2021-03-26 00:45:19",
"duration": 1449
},
{
"code": 12,
"start": "2021-03-26 00:45:19",
"end": "2021-03-26 01:10:54",
"duration": 1535
},
{
"code": 0,
"start": "2021-03-26 01:10:54",
"end": "2021-03-26 01:15:55",
"duration": 301
},
{
"code": 12,
"start": "2021-03-26 01:15:55",
"end": "2021-03-26 02:31:12",
"duration": 4517
},
{
"code": 0,
"start": "2021-03-26 02:31:12",
"end": "2021-03-26 02:56:40",
"duration": 1528
},
{
"code": 12,
"start": "2021-03-26 02:56:40",
"end": "2021-03-26 02:56:50",
"duration": 10
},
{
"code": 0,
"start": "2021-03-26 02:56:50",
"end": "2021-03-26 03:30:52",
"duration": 2042
},
{
"code": 12,
"start": "2021-03-26 03:30:52",
"end": "2021-03-26 03:31:01",
"duration": 9
},
{
"code": 0,
"start": "2021-03-26 03:31:01",
"end": "2021-03-26 04:11:00",
"duration": 2399
},
{
"code": 12,
"start": "2021-03-26 04:11:00",
"end": "2021-03-26 04:11:09",
"duration": 9
},
{
"code": 0,
"start": "2021-03-26 04:11:09",
"end": "2021-03-26 05:58:13",
"duration": 6424
},
{
"code": 0,
"start": "2021-03-26 05:58:13",
"end": "2021-03-26 08:00:00",
"duration": 7307
},
{
"code": 0,
"start": "2021-03-26 08:00:00",
"end": "2021-03-27 08:00:00",
"duration": 86400
},
{
"code": 0,
"start": "2021-03-27 08:00:00",
"end": "2021-03-27 22:01:26",
"duration": 50486
},
{
"code": 1,
"start": "2021-03-27 22:01:26",
"end": "2021-03-27 22:02:26",
"duration": 60
},
{
"code": 0,
"start": "2021-03-27 22:02:26",
"end": "2021-03-27 22:02:47",
"duration": 21
},
{
"code": 1,
"start": "2021-03-27 22:02:47",
"end": "2021-03-27 22:03:00",
"duration": 13
},
{
"code": 0,
"start": "2021-03-27 22:03:00",
"end": "2021-03-28 08:00:00",
"duration": 35820
},
{
"code": 0,
"start": "2021-03-28 08:00:00",
"end": "2021-03-29 05:46:49",
"duration": 78409
},
{
"code": 1,
"start": "2021-03-29 05:46:49",
"end": "2021-03-29 05:47:57",
"duration": 68
},
{
"code": 0,
"start": "2021-03-29 05:47:57",
"end": "2021-03-29 08:00:00",
"duration": 7923
},
{
"code": 0,
"start": "2021-03-29 08:00:00",
"end": "2021-03-29 16:34:54",
"duration": 30894
}
]
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="CURL" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/bm-cs-projects/12417/streams/s-0xAHfNh/state?timeoffset=0&start_date=20210301&end_date=20210302' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}'
```
{% endtab %}
{% endtabs %}
## The details of the state code
| Code | Name |
| ---- | ----------- |
| 0 | Running |
| 1 | Timeout |
| 4 | Paused |
| 6 | Invalid URL |
| 10 | Deleted |
| 12 | Mute |
# Recordings
Please make sure that your channels have enabled Timemap before getting the recording.
## Get the recording of the results.
`GET` `https://api-v2.acrcloud.com/api/bm-cs-projects/:pid/streams/:stream_id/recordings`
This endpoint allows you to get the recordings of the results of your channels.
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | -------------- |
| pid | number | The project id |
| stream\_id | string | The stream id |
#### Query Parameters
| Name | Type | Description |
| ---------------- | ------- | ------------------------------------------------------------------------------------------ |
| timestamp\_utc | string | The start time of the recording, the format is YYYYmmddHHMMSS (for example 20210101120809) |
| played\_duration | integer | The duration of the recording(seconds) |
| record\_before | integer | How many seconds of recording to add forward(default 0). |
| record\_after | integer | How many seconds of recording to add backwards(default 0). |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
| Accept | string | \*/\* |
{% tabs %}
{% tab title="200 Get recording successfully." %}
```
```
{% endtab %}
{% tab title="404 Could not get the recording." %}
```
{ "message": "The recording is not available." }
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="CURL" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/bm-cs-projects/10079/streams/s-XXXXXXX/recordings?timestamp_utc=20210607000210&played_duration=30' \
--header 'Accept: */*' \
--header 'Authorization: Bearer {your token}'
```
{% endtab %}
{% endtabs %}
# Analytics
This api is only applicable to projects bound to ACRCloud Music
## Get analytics data for the last 7 days
`GET` `https://api-v2.acrcloud.com/api/bm-cs-projects/:project_id/analytics/results`
#### Path Parameters
| Name | Type | Description |
| --------------------------------------------- | ------ | -------------- |
| project\_id\* | Number | The project id |
#### Query Parameters
| Name | Type | Description |
| ---------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| stats\_type\* | String | Type of data, including date, track, artists, label, stream.
If result\_type is custom, then only include date, track, stream.
|
| result\_type\* | String | Type of result, including music, custom |
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization\* | String | Bearer token |
| Accept\* | String | application/json |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
"data": {
"id": "aaaaaa285bccccccc9210ffc4cdddddd",
"project_id": 12345,
"stats_type": "date",
"result_type": "music",
"start_timestamp_utc": "2022-07-27 00:00:00",
"end_timestamp_utc": "2022-08-02 23:59:59",
"results": [
{
"date": "2022-07-27",
"play_time": 130057,
"plays": 1130,
"rank": 1
},
{
"date": "2022-07-28",
"play_time": 90462,
"plays": 917,
"rank": 2
},
{
"date": "2022-07-29",
"play_time": 138791,
"plays": 1178,
"rank": 3
},
{
"date": "2022-07-30",
"play_time": 159087,
"plays": 1126,
"rank": 4
},
{
"date": "2022-07-31",
"play_time": 161067,
"plays": 1209,
"rank": 5
},
{
"date": "2022-08-01",
"play_time": 133762,
"plays": 1187,
"rank": 6
},
{
"date": "2022-08-02",
"play_time": 135043,
"plays": 1195,
"rank": 7
}
]
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```shell
curl --location --request GET 'https://api-v2.acrcloud.com/api/bm-cs-projects/12345/analytics/results?result_type=music&stats_type=date' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}' \
```
{% endtab %}
{% endtabs %}
# User Reports
## Insert user results
`POST` `https://api-v2.acrcloud.com/api/bm-cs-projects/:pid/streams/:stream_id/user-reports`
This endpoint allows you to insert the results just like in Timemap or UCF.
#### Path Parameters
| Name | Type | Description |
| ---------- | ------ | -------------- |
| pid | number | The project id |
| stream\_id | string | The stream id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Accept | string | application/json |
| Authorization | string | Bearer token |
| Content-Type | string | application/json |
#### Request Body
| Name | Type | Description |
| ----------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| data | array | Result list (\[result1, result2, result3...]) |
| result.from | string | api |
| result.title | string | The title of the result |
| result.timeoffset | string | UTC time offsets (For example, UK time is UTC + 00:00, the timeoffset is 0; Hong Kong time is UTC + 08:00, the timeoffset is -480) |
| reuslt.start\_timestamp | string | YYYY-mm-dd HH:MM:SS (For example, 2021-02-01 12:13:14), it is your Local Time. |
| result.end\_timestamp | string | YYYY-mm-dd HH:MM:SS (For example, 2021-02-01 12:15:26), it is your Local Time. |
| result.user\_defined | string | Other fields of the result (For example, {"artists": "xxx", "album": "xxx", "isrc": "xxx"}) |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"id": 984590,
"result": {
"start_timestamp_utc": "2021-05-25 03:55:49",
"end_timestamp_utc": "2021-05-25 03:56:37",
"record_timestamp": "",
"title": "xxx",
"artists": "xxx",
"album": "xxx",
"acrid": "null",
"duration": 48,
"played_duration": 48,
"monitor_type": "",
"result_type": "custom",
"from": "api-report",
"raw_metadata": {
"title": "xxx",
"artist": "xxx",
"album": "xxx"
},
"start_timestamp_local": "2021-05-25 11:55:49",
"end_timestamp_local": "2021-05-25 11:56:37"
}
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="First Tab" %}
```bash
curl --location --request POST 'https://api-v2.acrcloud.com/api/bm-cs-projects/17913/stream_id/s-XXXXXX/user-reports' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}'
--header 'Content-Type: application/json' \
--data-raw '{"data":[{"from": "api", "title": "xxxx", "timeoffset": 0, "start_timestamp": "2021-02-01 12:13:14", "end_timestamp": "2021-02-01 12:15:26", "user_defined": {"artists": "xxx", "album": "xxx"}}]}'
```
{% endtab %}
{% endtabs %}
# Broadcast Database Projects
## Create a project
`POST` `https://api-v2.acrcloud.com/api/bm-bd-projects`
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
| Content-Type | string | application/json |
#### Request Body
| Name | Type | Description |
| ------- | ------ | ---------------------------------- |
| region | string | eu-west-1,us-west-2,ap-southeast-1 |
| name | string | The project name |
| buckets | array | Bucket ids array |
{% tabs %}
{% tab title="200 Cake successfully retrieved." %}
```
{
"data": {
"id": 12345,
"name": "test",
"uid": 2,
"region": "eu-west-1",
"bucket_ids": "14661",
"updated_at": "2021-02-22 03:38:28",
"created_at": "2021-02-22 03:38:27",
"access_key": "**********",
"buckets": [
{
"id": 14661,
"uid": 2,
"name": "test",
"type": "File",
"node": "10.12.12.236-850",
"state": 1,
"region": "eu-west-1",
"metadata_template": "isrc, artist, album",
"labels": [
"Music"
],
"net_type": 1,
"created_at": "2020-07-06 11:25:08",
"updated_at": "2020-07-06 11:25:08",
"num": 0,
"size": 0,
"access_permission": "private"
}
],
"config": {
"record": {
},
"ucf": {
},
"callback_result": {
"enabled": 0,
"type_name": "diy",
"diy_url": "",
"diy_send_type": 2,
"diy_send_noresult": 0,
"diy_result_type": -1,
"r3d_source": "",
"r3d_url": "",
"r3d_key1": "",
"r3d_key2": "",
"r3d_result_type": "0"
},
"callback_state": {
"enabled": 0,
"url": "",
"send_type": 2
},
"email_state": {
"email": "",
"type": 2
},
"access_permission": {
"add_tv": 0,
"edit_url": 0,
"can_modify": 1
}
},
"monitoring_num": 0,
"type": "BM-Database",
"status_check": 2
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request POST 'https://api-v2.acrcloud.com/api/bm-bd-projects' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}' \
--header 'Content-Type: application/json' \
--data-raw '{"region": "eu-west-1", "name": "test1", "buckets": [14661]}'
```
{% endtab %}
{% endtabs %}
## Update a project
`PUT` `https://api-v2.acrcloud.com/api/bm-bd-projects/:id`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------- |
| id | number | The project id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
| Content-Type | string | application/json |
#### Request Body
| Name | Type | Description |
| ------- | ------ | ---------------- |
| name | string | The project name |
| buckets | array | |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"id": 12345,
"name": "test2",
"uid": 2,
"region": "eu-west-1",
"bucket_ids": "23,14661",
"updated_at": "2021-02-22 03:44:08",
"created_at": "2021-02-22 03:38:27",
"access_key": "**************",
"buckets": [
{
"id": 23,
"uid": 0,
"name": "ACRCloud Music",
"type": "ACRCloudFile",
"node": "52.50.121.26-8870",
"state": 1,
"region": "global",
"metadata_template": "",
"labels": [
"Music"
],
"net_type": 0,
"created_at": "2015-05-05 04:22:19",
"updated_at": "2020-05-13 19:28:15",
"num": 72002117,
"size": 397184,
"access_permission": "private"
},
{
"id": 14661,
"uid": 72,
"name": "test",
"type": "File",
"node": "10.12.12.236-850",
"state": 1,
"region": "eu-west-1",
"metadata_template": "isrc, artist, album",
"labels": [
"Music"
],
"net_type": 1,
"created_at": "2020-07-06 11:25:08",
"updated_at": "2020-07-06 11:25:08",
"num": 0,
"size": 0,
"access_permission": "private"
}
],
"config": {
"record": {
},
"ucf": {
},
"callback_result": {
"enabled": 0,
"type_name": "diy",
"diy_url": "",
"diy_send_type": 2,
"diy_send_noresult": 0,
"diy_result_type": -1,
"r3d_source": "",
"r3d_url": "",
"r3d_key1": "",
"r3d_key2": "",
"r3d_result_type": "0"
},
"callback_state": {
"enabled": 0,
"url": "",
"send_type": 2
},
"email_state": {
"email": "",
"type": 2
},
"access_permission": {
"add_tv": 0,
"edit_url": 0,
"can_modify": 1
}
},
"monitoring_num": 0,
"type": "BM-Database",
"status_check": 2
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request PUT 'https://api-v2.acrcloud.com/api/bm-bd-projects/12345' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}' \
--header 'Content-Type: application/json' \
--data-raw '{"region": "eu-west-1", "name": "test2", "buckets": [14661, 23]}'
```
{% endtab %}
{% endtabs %}
## Delete a project
`DELETE` `https://api-v2.acrcloud.com/api/bm-bd-projects/:id`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------- |
| id | string | The project id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
{% tabs %}
{% tab title="204 " %}
```
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request DELETE 'https://api-v2.acrcloud.com/api/bm-bd-projects/12345' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}' \
```
{% endtab %}
{% endtabs %}
## List the projects
`GET` `https://api-v2.acrcloud.com/api/bm-bd-projects`
#### Query Parameters
| Name | Type | Description |
| ------ | ------ | ----------- |
| region | string | |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
{% tabs %}
{% tab title="200 " %}
```
{
"data": [
{
"id": 12345,
"name": "test",
"uid": 2,
"region": "eu-west-1",
"bucket_ids": "23",
"updated_at": "2020-07-27 03:35:51",
"created_at": "2020-06-16 10:09:35",
"access_key": "***************",
"buckets": [
{
"id": 23,
"uid": 0,
"name": "ACRCloud Music",
"type": "ACRCloudFile",
"node": "52.50.121.26-8870",
"state": 1,
"region": "global",
"metadata_template": "",
"labels": [
"Music"
],
"net_type": 0,
"created_at": "2015-05-05 04:22:19",
"updated_at": "2020-05-13 19:28:15",
"num": 72002117,
"size": 397184,
"access_permission": "private"
}
],
"config": {
"record": {
},
"ucf": {
},
"callback_result": {
"enabled": 0,
"type_name": "diy",
"diy_url": "",
"diy_send_type": 2,
"diy_send_noresult": 0,
"diy_result_type": 1,
"r3d_source": "",
"r3d_url": "",
"r3d_key1": "",
"r3d_key2": "",
"r3d_result_type": "0"
},
"callback_state": {
"enabled": 0,
"url": "",
"send_type": 2
},
"email_state": {
"email": "",
"type": 2
},
"access_permission": {
"add_tv": 0,
"edit_url": 0,
"can_modify": 1
}
},
"monitoring_num": 1,
"type": "BM-Database",
"status_check": 2
}
],
"links": {
"first": "https://api-v2.acrcloud.com/api/bm-bd-projects?page=1",
"last": "https://api-v2.acrcloud.com/api/bm-bd-projects?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "https://api-v2.acrcloud.com/api/bm-bd-projects",
"per_page": "20",
"to": 2,
"total": 2
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="CURL" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/bm-bd-projects?region=eu-west-1&page=1&per_page=20' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}' \
```
{% endtab %}
{% endtabs %}
## Set results callback URL
`POST` `https://api-v2.acrcloud.com/api/bm-bd-projects/:id/result-callback`
After you set the results callback URL, the monitoring system will post the result to your callback URL in real-time.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------- |
| id | string | the project id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
| Content-Type | string | application/json |
#### Request Body
| Name | Type | Description |
| -------------------------------- | ------ | ------------------------------------------------------------------------------------- |
| result\_callback\_url | string | set the callback url |
| result\_callback\_send\_noresult | number | result\_callback\_send\_noresult: whether inform you when no content detected. 0 or 1 |
| result\_callback\_ | string | result\_callback\_result\_type:
0: RealTime
1: Delay
|
{% tabs %}
{% tab title="200 " %}
```
{
"data":{
"id":12345,
"name":"monitor_test",
"uid":2,
"region":"eu-west-1",
"bucket_ids":"23",
"updated_at":"2019-11-18 03:34:09",
"created_at":"2019-03-19 03:15:48",
"access_key":"**************",
"buckets":[
{
"id":23,
"uid":0,
"name":"ACRCloud Music",
"type":"ACRCloudFile",
"node":"52.50.121.26-8870",
"state":1,
"region":"global",
"metadata_template":"",
"labels":[
"Music"
],
"net_type":0,
"created_at":"2015-05-05 04:22:19",
"updated_at":"2020-05-13 19:28:15",
"num":72002117,
"size":397184,
"access_permission":"private"
}
],
"config":{
"record":{
},
"ucf":{
},
"callback_result":{
"enabled":1,
"type_name":"diy",
"diy_url":"http://test.acrcloud.com",
"diy_send_type":2,
"diy_send_noresult":0,
"diy_result_type":0,
"r3d_source":"",
"r3d_url":"",
"r3d_key1":"",
"r3d_key2":"",
"r3d_result_type":"0"
},
"callback_state":{
"enabled":0,
"url":"",
"send_type":2
},
"email_state":{
"email":"",
"type":2
},
"access_permission":{
"add_tv":0,
"edit_url":1,
"can_modify":1
}
},
"monitoring_num":4,
"type":"BM-Database",
"status_check":2
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request POST 'https://api-v2.acrcloud.com/api/bm-bd-projects/12345/result-callback?type=diy' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your token}' \
--data-raw '{"result_callback_url": "http://*****", "result_callback_send_noresult": false, "result_callback_send_type": "2", "result_callback_result_type": "1"}'
```
{% endtab %}
{% endtabs %}
> The following is the example of the results of the monitoring system posting to your results callback URL
{% tabs %}
{% tab title="Sample result of Music(Callback)" %}
```
{
"stream_id": "100251",
"stream_name": "BBC Radio 1",
"stream_country": "United Kingdom",
"bucket_id": "23",
"status": 1,
"user_defined": {
"custom_id": "test_id"
},
"data": {
"status": {
"msg": "Success",
"version": "1.0",
"code": 0
},
"result_type": 0,
"metadata": {
"type": "delay",
"timestamp_utc": "2020-01-14 05:49:18",
"played_duration": 139,
"music": [
{
"album": {
"name": "I Know You"
},
"play_offset_ms": 19800,
"genres": [
{
"name": "Dance"
}
],
"contributors": {
"composers": [
"Craig David",
"Dan Smith",
"Fraser T Smith",
"Helen Culver"
],
"lyricists": [
"DANIEL CAMPBELL SMITH",
"FRASER LANCE THORNEYCROFT SMITH",
"CARMEN REECE",
"CRAIG ASHLEY DAVID"
]
},
"lyrics": {
"copyrights": [
"Universal Music Publishing Group"
]
},
"title": "I Know You",
"result_from": 3,
"release_date": "2017-11-10",
"sample_end_time_offset_ms": 9180,
"sample_begin_time_offset_ms": 3520,
"label": "Speakerbox/Insanity Records",
"duration_ms": 214760,
"score": 100,
"db_begin_time_offset_ms": 13860,
"artists": [
{
"name": "Craig David"
}
],
"db_end_time_offset_ms": 19520,
"external_ids": {
"isrc": [
"GBARL1701677",
"GBARL1800085"
],
"upc": [
"886446809496",
"886446747439",
"886446617541"
]
},
"acrid": "9564199dacc709123aee61c9556bacd2",
"external_metadata": {
"spotify": [
{
"track": {
"name": "I Know You",
"id": "34t13rSSZtr22CjcmroMmh"
},
"album": {
"name": "I Know You",
"id": "1SaIescHHJvcb0oyGVVIme"
},
"artists": [
{
"name": "Craig David",
"id": "2JyWXPbkqI5ZJa3gwqVa0c"
},
{
"name": "Bastille",
"id": "7EQ0qTo7fWT7DPxmxtSYEc"
}
]
},
{
"track": {
"name": "I Know You",
"id": "5lRzEC0Hyj92nEr9JkDxM2"
},
"album": {
"name": "The Time Is Now (Deluxe)",
"id": "51vRvV83RdWGP9FpzGe4SQ"
},
"artists": [
{
"name": "Craig David",
"id": "2JyWXPbkqI5ZJa3gwqVa0c"
},
{
"name": "Bastille",
"id": "7EQ0qTo7fWT7DPxmxtSYEc"
}
]
}
],
"deezer": [
{
"track": {
"name": "I Know You",
"id": "419827392"
},
"album": {
"name": "I Know You",
"id": "50234022"
},
"artists": [
{
"name": "Craig David",
"id": 110
},
{
"name": "Craig David",
"id": 110
},
{
"name": "Bastille",
"id": 1352097
}
]
},
{
"track": {
"name": "I Know You",
"id": "450179142"
},
"album": {
"name": "The Time Is Now (Deluxe)",
"id": "55045462"
},
"artists": [
{
"name": "Craig David",
"id": "110"
}
]
},
{
"track": {
"name": "I Know You",
"id": "478445942"
},
"album": {
"id": "59933892"
},
"artists": [
{
"id": 110,
"name": "Craig David"
},
{
"id": 1352097,
"name": "Bastille"
}
]
}
]
}
}
],
"record_timestamp": "20200114054918"
}
}
}
```
{% endtab %}
{% tab title="Sample result of Custom Files(Callback)" %}
```
{
"stream_id": "100251",
"stream_name": "BBC Radio 1",
"stream_country": "United Kingdom",
"bucket_id": "23",
"status": 1,
"user_defined": {
"custom_id": "test_id"
},
"data": {
"status": {
"msg": "Success",
"code": 0,
"version": "1.0"
},
"metadata": {
"timestamp_utc": "2015-07-27 12:56:46",
"played_duration": 30,
"custom_files": [
{
"bucket_id": "51",
"title": "You are beautiful",
"artist": "James",
"acrid": "5343bc191634b042622bf474ed46121a",
"audio_id": "3",
}
]
},
"result_type": 0
}
}
```
{% endtab %}
{% endtabs %}
## Set state notification callback
`POST` `https://api-v2.acrcloud.com/api/bm-bd-projects/:id/state-notification`
After you set the state callback URL, the monitoring system will post the states to your callback URL in real-time when the state of the channel changes.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------- |
| id | number | The project id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
| Content-Type | string | application/json |
#### Request Body
| Name | Type | Description |
| -------------------- | ------ | ----------------------------------------------------------------------- |
| state\_callback\_url | string | If the streams state change, we will post a result to this url you set. |
{% tabs %}
{% tab title="200 " %}
```
{
"data":{
"id":12345,
"name":"monitor_test",
"uid":2,
"region":"eu-west-1",
"bucket_ids":"23",
"updated_at":"2019-11-18 03:34:09",
"created_at":"2019-03-19 03:15:48",
"access_key":"***************",
"buckets":[
{
"id":23,
"uid":0,
"name":"ACRCloud Music",
"type":"ACRCloudFile",
"node":"52.50.121.26-8870",
"state":1,
"region":"global",
"metadata_template":"",
"labels":[
"Music"
],
"net_type":0,
"created_at":"2015-05-05 04:22:19",
"updated_at":"2020-05-13 19:28:15",
"num":72002117,
"size":397184,
"access_permission":"private"
}
],
"config":{
"record":{
},
"ucf":{
},
"callback_result":{
"enabled":0,
"type_name":"diy",
"diy_url":"",
"diy_send_type":2,
"diy_send_noresult":0,
"diy_result_type":0,
"r3d_source":"",
"r3d_url":"",
"r3d_key1":"",
"r3d_key2":"",
"r3d_result_type":"0"
},
"callback_state":{
"enabled":1,
"url":"http://test.acrcloud.com",
"send_type":2
},
"email_state":{
"email":"",
"type":2
},
"access_permission":{
"add_tv":0,
"edit_url":1,
"can_modify":1
}
},
"monitoring_num":4,
"type":"BM-Database",
"status_check":2
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request POST 'https://api-v2.acrcloud.com/api/bm-bd-projects/12345/state-notification' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your token}' \
--data-raw '{"state_callback_url": "http://www.xxxx.com/state_callback", "state_callback_type": "2"}'
```
{% endtab %}
{% endtabs %}
#### Example of monitoring system sending state data to your callback URL
```
{
"status":[
{
"stream_name":"Radio Fermo Uno",
"code":6,
"timestamp":"2022-01-22 14:02:00",
"stream_id":"222195",
"state":"invalid_url",
"type":"unknown"
}
]
}
```
#### The details of the state code
| Code | State Name |
| ---- | ----------- |
| 0 | Running |
| 1 | Timeout |
| 4 | Paused |
| 6 | Invaild URL |
| 10 | Deleted |
| 12 | Mute |
# Channels
## List the channels in this project
`GET` `https://api-v2.acrcloud.com/api/bm-bd-projects/:pid/channels`
This endpoint allows you to get free cakes.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------- |
| id | string | The project id |
#### Query Parameters
| Name | Type | Description |
| ------------- | ------ | ----------------------------------------------------------------- |
| state | string | All,Running,Timeout,Paused,Invalid URL,Mute,Other. Default is All |
| timemap | string | 0 or 1 |
| search\_type | string | channel\_id, channel\_name, city, custom\_id, mytuner\_id |
| search\_value | string | |
| page | number | The page number |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
{% tabs %}
{% tab title="200 Cake successfully retrieved." %}
```
{
"data": [
{
"uid": 19,
"project_id": 179,
"id": 100251,
"type": "Radio",
"name": "BBC Radio 1",
"sub_title": "London - 98.8 FM",
"language": "English",
"city": "London",
"province": null,
"country": "United Kingdom",
"continent": "Europe",
"website": "http://www.bbc.co.uk/radio1",
"twitter": "http://twitter.com/BBCR1",
"mytuner": "https://mytuner-radio.com/radio/409791",
"urls": [],
"status_code": 0,
"monitor_at": "2018-02-26 07:56:50",
"timemap": 0,
"user_defined": [],
"add_at": "2020-03-25 00:00:00"
},
{
"uid": 19,
"project_id": 179,
"id": 100252,
"type": "Radio",
"name": "BBC Radio 2",
"sub_title": "London - 89.1 FM",
"language": "English",
"city": "London",
"province": null,
"country": "United Kingdom",
"continent": "Europe",
"website": "http://www.bbc.co.uk/radio2",
"twitter": "http://twitter.com/BBCRadio2",
"mytuner": "https://mytuner-radio.com/radio/409758",
"urls": [],
"status_code": 0,
"monitor_at": "2018-02-26 07:56:50",
"timemap": 0,
"user_defined": [],
"add_at": "2020-03-25 00:00:00"
}
],
"links": {
"first": "https://api-v2.acrcloud.com/api/bm-bd-projects/179/channels?page=1",
"last": "https://api-v2.acrcloud.com/api/bm-bd-projects/179/channels?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "https://api-v2.acrcloud.com/api/bm-bd-projects/179/channels",
"per_page": 50,
"to": 2,
"total": 2
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/bm-bd-projects/179/channels' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}'
```
{% endtab %}
{% endtabs %}
## Add channels to your project
`POST` `https://api-v2.acrcloud.com/api/bm-bd-projects/:pid/channels`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------- |
| pid | number | The project id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
| Content-Type | string | application/json |
#### Request Body
| Name | Type | Description |
| -------- | ------ | ----------------- |
| channels | string | channel\_id array |
{% tabs %}
{% tab title="204 " %}
```
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request POST 'https://api-v2.acrcloud.com/api/bm-bd-projects/12345/channels' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}' \
--header 'Content-Type: application/json' \
--data-raw '{"channels": [238766]}'
```
{% endtab %}
{% endtabs %}
## Delete channels from your project
`DELETE` `https://api-v2.acrcloud.com/api/bm-bd-projects/:pid/channels/:channel_ids`
#### Path Parameters
| Name | Type | Description |
| ------------ | ------ | ---------------------------- |
| pid | string | The project id |
| channel\_ids | string | One or multiple channel ids, |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
{% tabs %}
{% tab title="204 " %}
```
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request DELETE 'https://api-v2.acrcloud.com/api/bm-bd-projects/12345/channels/238766?is_marked=0' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}' \
```
{% endtab %}
{% endtabs %}
## Set custom\_id for channel
`POST` `https://api-v2.acrcloud.com/api/bm-bd-projects/:pid/channels/:channel_id/user-defined`
#### Path Parameters
| Name | Type | Description |
| ----------- | ------ | -------------- |
| pid | string | The project id |
| channel\_id | string | The channel id |
#### Query Parameters
| Name | Type | Description |
| ---------- | ------ | ----------------------- |
| custom\_id | string | Custom ID, can be empty |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
**Response**
{% tabs %}
{% tab title="200" %}
```json
{
"data": {
"uid": 72,
"project_id": 3086,
"id": 219046,
"type": "Radio",
"name": "Cadena COPE",
"sub_title": "Madrid - 999 AM",
"language": "",
"city": "Madrid",
"province": null,
"country": "Spain",
"continent": "Europe",
"website": "http://www.cope.es/",
"twitter": "https://twitter.com/cope_es",
"mytuner": "https://mytuner-radio.com/radio/410556",
"urls": [],
"status_code": 0,
"monitor_at": "2019-06-06 08:55:41",
"timemap": 0,
"timemap_lifecycle": null,
"coversong": 0,
"coversong_at": "",
"user_defined": {
"id": "custom_id"
},
"add_at": "2025-02-24 06:45:10"
}
}
```
{% endtab %}
{% endtabs %}
# Channels Results
## Get non-real-time results of channel monitoring
`GET` `https://api-v2.acrcloud.com/api/bm-bd-projects/:pid/channels/:channel_id/results`
#### Path Parameters
| Name | Type | Description |
| ----------- | ------ | -------------- |
| pid | number | The project id |
| channel\_id | number | The channel id |
#### Query Parameters
| Name | Type | Description |
| --------------------- | ------ | --------------------------------------------------------------------------------------------------------------------- |
| type | string | last: get the last result
day: get the day result
Default is day.
|
| date | string | get the results for a certain day you specified. The format is YYYYmmdd (E.g. 20210201) |
| min\_duration | number | Only return the results of played\_duration greater than or equal to min\_duration seconds (default: 0) |
| max\_duration | number | Only return the results of played\_duration less than or equal to max\_duration seconds (default: 3600) |
| isrc\_country | string | Only return results that match the isrc country code (E.g. DE, FR, IT, US) |
| with\_false\_positive | number | 0: does not return results marked as false positive. (Default)
1: returns results marked false positive.
|
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
{% tabs %}
{% tab title="200 Cake successfully retrieved." %}
```
{
"data": [
{
"status": {
"msg": "Success",
"code": 0,
"version": "1.0"
},
"result_type": 0,
"metadata": {
"type": "delay",
"timestamp_utc": "2021-01-07 10:20:25",
"played_duration": 117,
"music": [
{
"album": {
"name": "Shoot For The Stars Aim For The Moon"
},
"play_offset_ms": 30520,
"sample_begin_time_offset_ms": 2420,
"title": "What You Know Bout Love",
"result_from": 3,
"release_date": "2020-07-03",
"sample_end_time_offset_ms": 8460,
"genres": [
{
"name": "Hip Hop"
}
],
"label": "Victor Victor Worldwide",
"db_end_time_offset_ms": 29240,
"score": 100,
"db_begin_time_offset_ms": 23200,
"artists": [
{
"name": "Pop Smoke"
}
],
"duration_ms": 160000,
"external_ids": {
"isrc": [
"USUM72013339",
"USUM72013343",
"QZNMT2001964"
],
"upc": [
"00602507456573",
"00602507456672",
"00602507456566"
]
},
"acrid": "dda6ca5475ba126aa02b88ebe9b9b4cd",
"external_metadata": {
"spotify": [
{
"album": {
"name": "Shoot For The Stars Aim For The Moon",
"id": "7e7t0MCrNDcJZsPwUKjmOc"
},
"track": {
"name": "What You Know Bout Love",
"id": "1tkg4EHVoqnhR6iFEXb60y"
},
"artists": [
{
"name": "Pop Smoke",
"id": "0eDvMgVFoNV3TpwtrVCoTj"
}
]
},
{
"album": {
"name": "Shoot For The Stars Aim For The Moon",
"id": "3BjyBrktXCnnJ0gHifkyAk"
},
"track": {
"name": "What You Know Bout Love",
"id": "4g7ErSF4oImNnITtyiFowz"
},
"artists": [
{
"name": "Pop Smoke",
"id": "0eDvMgVFoNV3TpwtrVCoTj"
}
]
},
{
"album": {
"name": "Shoot For The Stars Aim For The Moon (Deluxe)",
"id": "45HGJedVnKuOXNFW8fVuDz"
},
"track": {
"name": "What You Know Bout Love",
"id": "3jia9xE2RlTZKSy78z1mIz"
},
"artists": [
{
"name": "Pop Smoke",
"id": "0eDvMgVFoNV3TpwtrVCoTj"
}
]
}
],
"deezer": [
{
"album": {
"name": ""
},
"track": {
"name": "What You Know Bout Love",
"id": "1081877402"
},
"artists": [
{
"name": "Pop Smoke"
}
]
}
]
}
}
],
"record_timestamp": "20210107102025"
}
}
]
}
```
{% endtab %}
{% tab title="404 Could not find a cake matching this query." %}
```
{ "message": "Ain't no cake like that."}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl #day" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/bm-bd-projects/179/channels/100251/results?type=day&date=20210201' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% tab title="Curl #last" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/bm-bd-projects/179/channels/100251/results?type=last' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}'
```
{% endtab %}
{% endtabs %}
## Get real-time results of channel monitoring
`GET` `https://api-v2.acrcloud.com/api/bm-bd-projects/:pid/channels/:channel_id/realtime_results`
#### Path Parameters
| Name | Type | Description |
| ----------- | ------ | -------------- |
| pid | number | The project id |
| channel\_id | number | The channel id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"status": {
"msg": "Success",
"code": 0,
"version": "1.0"
},
"result_type": 0,
"metadata": {
"timestamp_utc": "2021-02-24 08:29:44",
"music": [
{
"album": {
"name": "Coco"
},
"play_offset_ms": 13240,
"sample_begin_time_offset_ms": 0,
"contributors": {
"composers": [
"Golden Landis Von Jones",
"Omer Fedi",
"Jace Logan Jennings",
"Jonathan Kirk"
],
"lyricists": [
"Golden Landis Von Jones",
"Omer Fedi",
"Jace Logan Jennings",
"Jonathan Kirk"
]
},
"title": "Coco",
"result_from": 3,
"release_date": "2020-12-04",
"sample_end_time_offset_ms": 9080,
"genres": [
{
"name": "Rap"
}
],
"label": "SME - Records/Columbia",
"duration_ms": 142000,
"score": 100,
"db_begin_time_offset_ms": 3520,
"artists": [
{
"name": "24kGoldn"
},
{
"name": "DaBaby"
}
],
"db_end_time_offset_ms": 12600,
"external_ids": {
"isrc": [
"USQX92004163",
"USANG2128624",
"USQX92005136"
],
"upc": [
"886448929031",
"024543215974",
"886448929048"
]
},
"acrid": "052b6bc22d274731acf51d51449a3a5f",
"external_metadata": {
"spotify": [
{
"album": {
"name": "Coco (feat. DaBaby)"
},
"track": {
"name": "Coco (feat. DaBaby)",
"id": "2V6pjeOCuPBVlatcWTXUtP"
},
"artists": [
{
"name": "24kGoldn"
},
{
"name": "DaBaby"
}
]
}
],
"deezer": [
{
"album": {
"name": ""
},
"track": {
"name": "Coco (feat. DaBaby)",
"id": "1160241372"
},
"artists": [
{
"name": "24kgoldn"
},
{
"name": "DaBaby"
}
]
}
]
}
}
]
}
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/bm-bd-projects/179/channels/100251/realtime_results' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}'
```
{% endtab %}
{% endtabs %}
#### The following is a sample script that displays the results in real-time
```
[
"method" => "GET",
"header" => "Accept: application/json\r\n" .
"Authorization: Bearer " . $token . "\r\n"
]
];
$context = stream_context_create($opts);
$data = file_get_contents("https://api-v2.acrcloud.com/api/bm-bd-projects/" . $project_id . "/channels/" . $channel_id . "/realtime_results", false, $context);
$obj = json_decode($data, true);
# var_dump($obj);
$title = "";
$artists = "";
$metadata = $obj['data']['metadata'];
if (array_key_exists('music', $metadata)) {
$music = $metadata['music'][0];
$title = $music['title'];
$arlist = [];
if (array_key_exists('artists', $music)) {
foreach($music['artists'] as $ar) {
$arlist[] = $ar['name'];
}
}
if (count($arlist) > 0) {
$artists = implode(', ', $arlist);
}
}
$ret = ['title'=>$title, 'artists'=>$artists, 'result'=>$obj];
print_r(json_encode($ret));
?>
```
## Getting results not recognized but detected as music. (Note: This API is only available for channels with music detection enabled)
`GET` `https://api-v2.acrcloud.com/api/bm-bd-projects/:pid/channels/:channel_id/unknown_results`
#### Path Parameters
| Name | Type | Description |
| --------------------------------------------- | ------ | -------------- |
| pid\* | Number | The project id |
| channel\_id\* | Number | channel\_id |
#### Query Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------- |
| date\* | String | Get all the results on this date. The format is YYYYmmdd (E.g. 20210201) |
| min\_duration | Number | Only return the results of played\_duration greater than or equal to min\_duration seconds (default: 0) |
| max\_duration | Number | Only return the results of played\_duration less than or equal to max\_duration seconds (default: 3600) |
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization\* | String | Bearer token |
| Accept\* | String | application/json |
{% tabs %}
{% tab title="200: OK " %}
````json
```json
{
"data": [
{
"start_timestamp_utc": "2023-11-01 00:00:00",
"end_timestamp_utc": "2023-11-01 00:00:12",
"played_duration": 12,
"name": "Foreground music"
},
{
"start_timestamp_utc": "2023-11-01 00:00:26",
"end_timestamp_utc": "2023-11-01 00:00:29",
"played_duration": 3,
"name": "Foreground music"
},
{
"start_timestamp_utc": "2023-11-01 00:00:29",
"end_timestamp_utc": "2023-11-01 00:00:39",
"played_duration": 10,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-11-01 00:01:39",
"end_timestamp_utc": "2023-11-01 00:01:56",
"played_duration": 17,
"name": "Background music"
},
{
"start_timestamp_utc": "2023-11-01 00:02:52",
"end_timestamp_utc": "2023-11-01 00:03:16",
"played_duration": 24,
"name": "Background music"
},
...
]
}
```
````
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```
curl --location 'https://api-v2.acrcloud.com/api/bm-bd-projects/1234/channels/200232/unknown_results?date=20231101' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% endtabs %}
# Channels State
## Get the state of the channel
`GET` `https://api-v2.acrcloud.com/api/bm-bd-projects/:pid/channels/:channel_id/state`
#### Path Parameters
| Name | Type | Description |
| ----------- | ------ | -------------- |
| pid | number | The project id |
| channel\_id | number | The channel id |
#### Query Parameters
| Name | Type | Description |
| ----------- | ------ | --------------------------------------------------------------------------------------------------------- |
| timeoffset | string | Time offset from UTC(e.g: The timeoffset of Tokyo(UTC+9) is -540, the timeoffset of Dubai(UTC+4) is -240) |
| start\_date | string | Start date(YYYYmmdd, e.g: 20210301) |
| end\_date | string | End date(YYYYmmdd, e.g: 20210302) |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"total_time": 318895,
"valid_time": 312323,
"timeoffset": 0,
"state_list": [
{
"code": 0,
"start": "2021-03-26 00:00:00",
"end": "2021-03-26 00:06:38",
"duration": 398
},
{
"code": 12,
"start": "2021-03-26 00:06:38",
"end": "2021-03-26 00:10:58",
"duration": 260
},
{
"code": 0,
"start": "2021-03-26 00:10:58",
"end": "2021-03-26 00:19:40",
"duration": 522
},
{
"code": 12,
"start": "2021-03-26 00:19:40",
"end": "2021-03-26 00:21:10",
"duration": 90
},
{
"code": 0,
"start": "2021-03-26 00:21:10",
"end": "2021-03-26 00:45:19",
"duration": 1449
},
{
"code": 12,
"start": "2021-03-26 00:45:19",
"end": "2021-03-26 01:10:54",
"duration": 1535
},
{
"code": 0,
"start": "2021-03-26 01:10:54",
"end": "2021-03-26 01:15:55",
"duration": 301
},
{
"code": 12,
"start": "2021-03-26 01:15:55",
"end": "2021-03-26 02:31:12",
"duration": 4517
},
{
"code": 0,
"start": "2021-03-26 02:31:12",
"end": "2021-03-26 02:56:40",
"duration": 1528
},
{
"code": 12,
"start": "2021-03-26 02:56:40",
"end": "2021-03-26 02:56:50",
"duration": 10
},
{
"code": 0,
"start": "2021-03-26 02:56:50",
"end": "2021-03-26 03:30:52",
"duration": 2042
},
{
"code": 12,
"start": "2021-03-26 03:30:52",
"end": "2021-03-26 03:31:01",
"duration": 9
},
{
"code": 0,
"start": "2021-03-26 03:31:01",
"end": "2021-03-26 04:11:00",
"duration": 2399
},
{
"code": 12,
"start": "2021-03-26 04:11:00",
"end": "2021-03-26 04:11:09",
"duration": 9
},
{
"code": 0,
"start": "2021-03-26 04:11:09",
"end": "2021-03-26 05:58:13",
"duration": 6424
},
{
"code": 0,
"start": "2021-03-26 05:58:13",
"end": "2021-03-26 08:00:00",
"duration": 7307
},
{
"code": 0,
"start": "2021-03-26 08:00:00",
"end": "2021-03-27 08:00:00",
"duration": 86400
},
{
"code": 0,
"start": "2021-03-27 08:00:00",
"end": "2021-03-27 22:01:26",
"duration": 50486
},
{
"code": 1,
"start": "2021-03-27 22:01:26",
"end": "2021-03-27 22:02:26",
"duration": 60
},
{
"code": 0,
"start": "2021-03-27 22:02:26",
"end": "2021-03-27 22:02:47",
"duration": 21
},
{
"code": 1,
"start": "2021-03-27 22:02:47",
"end": "2021-03-27 22:03:00",
"duration": 13
},
{
"code": 0,
"start": "2021-03-27 22:03:00",
"end": "2021-03-28 08:00:00",
"duration": 35820
},
{
"code": 0,
"start": "2021-03-28 08:00:00",
"end": "2021-03-29 05:46:49",
"duration": 78409
},
{
"code": 1,
"start": "2021-03-29 05:46:49",
"end": "2021-03-29 05:47:57",
"duration": 68
},
{
"code": 0,
"start": "2021-03-29 05:47:57",
"end": "2021-03-29 08:00:00",
"duration": 7923
},
{
"code": 0,
"start": "2021-03-29 08:00:00",
"end": "2021-03-29 16:34:54",
"duration": 30894
}
]
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="CURL" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/bm-bd-projects/1234/channels/295704/state?timeoffset=0&start_date=20210301&end_date=20210302' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}'
```
{% endtab %}
{% endtabs %}
## The details of the state code
| Code | Name |
| ---- | ----------- |
| 0 | Running |
| 1 | Timeout |
| 4 | Paused |
| 6 | Invalid URL |
| 10 | Deleted |
| 12 | Mute |
# Recordings
Please make sure that your channels have enabled Timemap before getting the recording.
## Get the recording of the results.
`GET` `https://api-v2.acrcloud.com/api/bm-bd-projects/:pid/channels/:channel_id/recordings`
This endpoint allows you to get the recordings of the results of your channels.
#### Path Parameters
| Name | Type | Description |
| ----------- | ------ | --------------- |
| pid | number | The project id. |
| channel\_id | number | The channel id. |
#### Query Parameters
| Name | Type | Description |
| ---------------- | ------- | ------------------------------------------------------------------------------------------- |
| timestamp\_utc | string | The start time of the recording, the format is YYYYmmddHHMMSS (for example 20210101120809). |
| played\_duration | integer | The duration of the recording(seconds). |
| record\_before | integer | How many seconds of recording to add forward(default 0). |
| record\_after | integer | How many seconds of recording to add backwards(default 0). |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
| Accept | string | \*/\* |
{% tabs %}
{% tab title="200 Get recording successfully." %}
```
```
{% endtab %}
{% tab title="404 Could not get the recording." %}
```
{ "message": "The recording is not available." }
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="CURL" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/bm-bd-projects/100079/channels/100123/recordings?timestamp_utc=20210601121314&played_duration=30' \
--header 'Accept: */*' \
--header 'Authorization: Bearer {your token}'
```
{% endtab %}
{% endtabs %}
# Analytics
This api is only applicable to projects bound to ACRCloud Music
## Get analytics data for the last 7 days
`GET` `https://api-v2.acrcloud.com/api/bm-bd-projects/:project_id/analytics/results`
#### Path Parameters
| Name | Type | Description |
| --------------------------------------------- | ------ | -------------- |
| project\_id\* | Number | The project id |
#### Query Parameters
| Name | Type | Description |
| ---------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| stats\_type\* | String | Type of data, including date, track, artists, label, channel.
If result\_type is custom, then only include date, track, channel.
|
| result\_type\* | String | Type of result, including music, custom |
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization\* | String | Bearer token |
| Accept\* | String | application/json |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
"data": {
"id": "ddddcbffeccc2daf603dddde4ed0dddd",
"project_id": 1234,
"stats_type": "date",
"result_type": "music",
"start_timestamp_utc": "2022-07-27 00:00:00",
"end_timestamp_utc": "2022-08-02 23:59:59",
"results": [
{
"date": "2022-07-27",
"play_time": 461059,
"plays": 4249,
"rank": 1
},
{
"date": "2022-07-28",
"play_time": 479187,
"plays": 4434,
"rank": 2
},
{
"date": "2022-07-29",
"play_time": 466170,
"plays": 4211,
"rank": 3
},
{
"date": "2022-07-30",
"play_time": 451512,
"plays": 3863,
"rank": 4
},
{
"date": "2022-07-31",
"play_time": 479693,
"plays": 4174,
"rank": 5
},
{
"date": "2022-08-01",
"play_time": 468885,
"plays": 4256,
"rank": 6
},
{
"date": "2022-08-02",
"play_time": 466158,
"plays": 4091,
"rank": 7
}
]
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```shell
curl --location --request GET 'https://api-v2.acrcloud.com/api/bm-bd-projects/1234/analytics/results?result_type=music&stats_type=date' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}' \
```
{% endtab %}
{% endtabs %}
# User Reports
## Insert user results
`POST` `https://api-v2.acrcloud.com/api/bm-bd-projects/:pid/channels/:channel_id/user-reports`
This endpoint allows you to insert the results just like in Timemap or UCF
#### Path Parameters
| Name | Type | Description |
| ----------- | ------ | -------------- |
| pid | string | The project id |
| channel\_id | string | The channel id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Accept | string | application/json |
| Authorization | string | Bearer token |
| Content-Type | string | application/json |
#### Request Body
| Name | Type | Description |
| ----------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| data | array | Result list (\[result1, result2, result3...]) |
| result.from | string | api |
| result.title | string | The title of the result |
| result.timeoffset | number | UTC time offsets (For example, UK time is UTC + 00:00, the timeoffset is 0; Hong Kong time is UTC + 08:00, the timeoffset is -480) |
| result.start\_timestamp | string | YYYY-mm-dd HH:MM:SS (For example, 2021-02-01 12:13:14), it is your Local Time. |
| result.end\_timestamp | string | YYYY-mm-dd HH:MM:SS (For example, 2021-02-01 12:15:26), it is your Local Time. |
| result.user\_defined | object | Other fields of the result (For example, {"artists": "xxx", "album": "xxx", "isrc": "xxx"}) |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"id": 984587,
"result": {
"start_timestamp_utc": "2021-05-25 02:35:42",
"end_timestamp_utc": "2021-05-25 02:36:25",
"title": "xxx",
"artist": "",
"album": "",
"acrid": "null",
"duration": 43,
"played_duration": 43,
"monitor_type": "",
"result_type": "custom",
"from": "api-report",
"raw_metadata": {
"title": "xxx",
"artists": "xxx",
"album": "xxx"
},
"start_timestamp_local": "2021-05-25 10:35:42",
"end_timestamp_local": "2021-05-25 10:36:25"
}
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="CURL" %}
```bash
curl --location --request POST 'https://api-v2.acrcloud.com/api/bm-bd-projects/179/channels/100251/user-reports' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}'
--header 'Content-Type: application/json' \
--data-raw '{"data":[{"from": "api", "title": "xxxx", "timeoffset": 0, "start_timestamp": "2021-02-01 12:13:14", "end_timestamp": "2021-02-01 12:15:26", "user_defined": {"artists": "xxx", "album": "xxx"}}]}'
```
{% endtab %}
{% endtabs %}
# Historical Results Projects
## Create a project
`POST` `https://api-v2.acrcloud.com/api/bm-hist-projects`
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
| Content-Type | string | application/json |
#### Request Body
| Name | Type | Description |
| ------------- | ------ | ---------------------------------- |
| region | string | eu-west-1,us-west-2,ap-southeast-1 |
| name | string | The project name |
| stations | array | Station ids array |
| project\_type | string | radio,tv |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"uid": 1,
"name": "tv",
"region": "eu-west-1",
"access_key": "xxxxxxxxxxxxxxxxxxxxxxx",
"state": 1,
"months": [],
"total_price": 0,
"total_months": 0,
"unit_price": 50,
"payment_status": 0,
"paid_amount": 0,
"paid_at": "",
"report_id": 0,
"updated_at": "2026-05-08 09:20:45",
"created_at": "2026-05-08 09:20:45",
"id": 1,
"total_channels": 0,
"total_resutls": 0,
"total_durations": 0,
"monthly_details": {},
"project_type": "tv"
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request POST 'https://api-v2.acrcloud.com/api/bm-hist-projects' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}' \
--header 'Content-Type: application/json' \
--data-raw '{"region":"eu-west-1","name":"test","project_type":"tv","stations":[]}'
```
{% endtab %}
{% endtabs %}
## List the projects
`GET` `https://api-v2.acrcloud.com/api/bm-hist-projects`
#### Query Parameters
| Name | Type | Description |
| --------- | ------ | ---------------------------------- |
| region | string | eu-west-1,us-west-2,ap-southeast-1 |
| page | number | Page number |
| per\_page | number | Items per page |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
{% tabs %}
{% tab title="200 " %}
```
{
"data": [
{
"id": 1,
"uid": 1,
"name": "tv2",
"region": "eu-west-1",
"access_key": "xxxxxxxxxxxxxxxxxxxxx",
"state": 1,
"months": [],
"total_price": 0,
"total_months": 0,
"unit_price": 50,
"payment_status": 0,
"paid_amount": 0,
"paid_at": "",
"report_id": 0,
"updated_at": "2026-05-08 09:20:45",
"created_at": "2026-05-08 09:20:45",
"total_channels": 0,
"total_resutls": 0,
"total_durations": 0,
"monthly_details": {},
"project_type": "tv"
}
],
"links": {
"first": "https://api-v2.acrcloud.com/api/bm-hist-projects?page=1",
"last": "https://api-v2.acrcloud.com/api/bm-hist-projects?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "https://api-v2.acrcloud.com/api/bm-hist-projects",
"per_page": "20",
"to": 1,
"total": 1
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/bm-hist-projects?region=eu-west-1&page=1&per_page=20' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}'
```
{% endtab %}
{% endtabs %}
## Get a project
`GET` `https://api-v2.acrcloud.com/api/bm-hist-projects/:id`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------- |
| id | number | The project id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"id": 1,
"uid": 1,
"name": "tv2",
"region": "eu-west-1",
"access_key": "xxxxxxxxxxxxxxxxxxxx",
"state": 1,
"months": [],
"total_price": 0,
"total_months": 0,
"unit_price": 50,
"payment_status": 0,
"paid_amount": 0,
"paid_at": "",
"report_id": 0,
"updated_at": "2026-05-08 09:20:45",
"created_at": "2026-05-08 09:20:45",
"total_channels": 0,
"total_resutls": 0,
"total_durations": 0,
"monthly_details": {},
"project_type": "tv"
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/bm-hist-projects/1' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}'
```
{% endtab %}
{% endtabs %}
# Channels Results
## Get results of a channel on a specified day
`GET` `https://api-v2.acrcloud.com/api/bm-hist-projects/:pid/channels/:channel_id/results`
#### Path Parameters
| Name | Type | Description |
| ----------- | ------ | -------------- |
| pid | number | The project id |
| channel\_id | number | The channel id |
#### Query Parameters
| Name | Type | Description |
| ---- | ------ | --------------------------------------------------------------------------------------- |
| date | string | Get the results for a certain day you specified. The format is YYYYmmdd (E.g. 20250221) |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token |
| Accept | string | application/json |
{% tabs %}
{% tab title="200 " %}
```
{
"data": [
{
"status": {
"msg": "Success",
"code": 0,
"version": "1.0"
},
"result_type": 0,
"metadata": {
"type": "historical",
"timestamp_utc": "2025-02-21 10:20:25",
"played_duration": 117,
"record_timestamp": "20250221102025",
"music": [
{
"title": "What You Know Bout Love",
"artists": [
{
"name": "Pop Smoke"
}
],
"album": {
"name": "Shoot For The Stars Aim For The Moon"
},
"release_date": "2020-07-03",
"duration_ms": 160000,
"score": 100,
"acrid": "dda6ca5475ba126aa02b88ebe9b9b4cd",
"external_ids": {
"isrc": [
"USUM72013339"
],
"upc": [
"00602507456573"
]
}
}
]
}
}
]
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/bm-hist-projects/1/channels/243253/results?date=20250221' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}'
```
{% endtab %}
{% endtabs %}
# METADATA
# Music (Broadcast Monitoring with Broadcast Database)
Example of JSON result with ACRCloud Music bucket in Broadcast Database of Broadcast Monitoring service.
```bash
{
"status": {
"msg": "Success",
"code": 0,
"version": "1.0"
},
"result_type": 0,
"metadata": {
"type": "delay",
"timestamp_utc": "2020-07-06 04:38:43",
"played_duration": 73,
"music": [
{
"album": {
"name": "Wish"
},
"play_offset_ms": 154600,
"sample_begin_time_offset_ms": 0,
"lyrics": {
"copyrights": [
"Universal Music Publishing Group"
]
},
"contributors": {
"composers": [
"Perry Bamonte",
"Porl Thompson",
"Boris Williams",
"Simon Gallup",
"Robert Smith"
],
"lyricists": [
"Boris Williams",
"Porl Thompson",
"Perry Bamonte",
"Robert James Smith",
"Simon Johnathon Gallup"
]
},
"title": "Friday I'm In Love ( LP Version )",
"result_from": 3,
"release_date": "1992-04-07",
"sample_end_time_offset_ms": 9120,
"genres": [
{
"name": "Pop"
}
],
"label": "Elektra Records",
"db_end_time_offset_ms": 154540,
"score": 100,
"db_begin_time_offset_ms": 145420,
"artists": [
{
"name": "The Cure"
}
],
"duration_ms": 214400,
"external_ids": {
"isrc": [
"USEE10180267",
"USEE19200008",
"GBALB9200002"
],
"iswc": [
"T0100954037"
],
"upc": [
"075596130967",
"075596211765",
"00731451326127"
]
},
"acrid": "4b10ecaa3dbcc60e9f7924919722e133",
"external_metadata": {
"musicbrainz": [
{
"track": {
"id": "59294de3-aaff-4d2d-bdc4-cbfe91de892e"
}
}
],
"spotify": [
{
"album": {
"name": "Wish",
"id": "6tCOXpiN1FvDBl0eT6WtG3"
},
"track": {
"name": "Friday I'm In Love",
"id": "20CNpCKq1oTdvekXaboyeq"
},
"artists": [
{
"name": "The Cure",
"id": "7bu3H8JO7d0UbMoVzbo70s"
}
]
}
],
"deezer": [
{
"album": {
"name": "Wish",
"id": "1344846"
},
"track": {
"name": "Friday I'm In Love ( LP Version )",
"id": "14611440"
},
"artists": [
{
"name": "The Cure",
"id": "381"
}
]
}
],
"youtube": [
{
"vid": "mGgMZpGYiy8"
}
]
}
}
],
"record_timestamp": "20200706043843"
}
}
```
### Metadata fields
| Name | Description |
| --------------------------------- | -------------------------------------------------------------------------------------------------- |
| music | Music fields |
| acrid | ACRCloud unique identifier |
| timestamp\_utc | Server time of sending results, Timestamp of the song started for custom monitoring, UTC time zone |
| title | Track title |
| album | Album fields |
| id | Identifier of the artists , album or 3rd parties fields |
| name | Name of the artists or album |
| artists | Artists fields |
| duration\_ms | Duration of the track in millisecond |
| play\_offset\_ms | The time position of the audio/song being played (millisecond) |
| external\_ids | External standard code |
| isrc | ISRC code |
| upc | UPC code |
| external\_metadata | External 3rd party IDs and metadata |
| track | Track fields |
| genres | Genres fields |
| label | Music label name |
| release\_date | Release data of the track, format:YYYY-MM-DD |
| spotify | Spotify fields |
| deezer | Deezer fields |
| lyricfind | LyricFind fields |
| lfid | LyricsFind's lyric ID |
| youtube | YouTube fields |
| vid | Youtube video ID |
| musicbrainz | MusicBrainz Identifier - MBID |
| iswc | ISWC - International Standard Musical Work Code |
| \*db\_begin\_time\_offset\_ms | Position of beginning of the recognition on database file (millisecond) |
| \*db\_end\_time\_offset\_ms | Position of end of the recognition on database file (millisecond) |
| \*sample\_begin\_time\_offset\_ms | Position of beginning of the recognition in sample file sent by SDK/API (millisecond) |
| \*sample\_end\_time\_offset\_ms | Position of end of the recognition in sample file sent by SDK/API (millisecond) |
| \*played\_duration | Actual duration of the track played in the streams for Broadcast Monitoring service, in second |
| score | Match confidence score. Range: 70 - 100 |
| lyrics | Lyrics related metadata |
| +copyrights | Publishers or copyright organizations for lyrics |
| +contributors | Contributor information for this track |
| +composers | Composers of the song |
| +lyricists | Writers of the lyrics |
| language | Language of the song, ISO 639-1 codes |
| +work | Publishing metadata fields for works |
| +ISWC | ISWC code |
| +name | Name of the work |
| +creators | The creator of the work |
| +ipi | IPI code for the party |
{% hint style="info" %}
**Please note: Only *****ACRID,*** ***Track Title, Artists Name***** and *****Album Name***** fields are required, other fields are optional.**
\* fields are visible in Broadcast Monitoring service only, if you want to use these fields in recognition service, please contact us.\
\
+fields are visible upon request, please contact us if you need those fields.
{% endhint %}
# Custom Files
An example of custom-defined metadata for Audio & Video Recognition, Broadcast Monitoring, Hybrid Recognition and Offline Recognition projects.
### JSON structure
```bash
{
"custom_files": [
{
"bucket_id": "51",
"title": "You are beautiful",
"artist": "James",
"acrid": "5343bc191634b042622bf474ed46121a",
"audio_id": "3"
}
]
}
```
### Metadata fields
| Name | Description |
| --------------------------------- | ------------------------------------------------------------------------------------- |
| custom\_files | Custom uploaded file fields |
| arcid | ACRCloud unique identifier |
| title | File name |
| audio\_id | User defined identifier |
| play\_offset\_ms | Position of the recognition in the file if the file was playing (millisecond) |
| \*db\_begin\_time\_offset\_ms | Position of beginning of the recognition on database file (millisecond) |
| \*db\_end\_time\_offset\_ms | Position of end of the recognition on database file (millisecond) |
| \*sample\_begin\_time\_offset\_ms | Position of beginning of the recognition in sample file sent by SDK/API (millisecond) |
| \*sample\_end\_time\_offset\_ms | Position of end of the recognition in sample file sent by SDK/API (millisecond) |
{% hint style="info" %}
***\* fields are visible in Broadcast Monitoring service only, if you want to use these fields in recognition service, please contact us.***
**Please note: Only *****Title, ARCID, Audio\_ID***** are required fields.**
{% endhint %}
# File Scanning
## Create a FS container
`POST` `https://api-v2.acrcloud.com/api/fs-containers`
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization\* | String | Bearer your\_token |
#### Request Body
| Name | Type | Description |
| --------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name\* | String | Your container name |
| region\* | String | eu-west-1,us-west-2,ap-southeast-1 |
| audio\_type\* | String | linein or recorded. Default is linein
linein: Audio of original file or stream without noise
recorded: Audio captured via microphone or noisy audio files
|
| buckets\* | Array | The project detects content from the buckets. The format is bucket id/name array. For example:
\[8881,8882,"ACRCloud Music"]
|
| engine\* | Number | 1:Audio Fingerprinting
2:Cover Songs
3:Audio Fingerprinting & Cover songs
4:Speech to Text
5: AI Music Detection
|
| policy\* | JSON | {"type":"traverse", "interval":0, "rec\_length:10}
or
{"type":"points", "points":3}
|
| callback\_url | String | Result callback url |
| deepright | Bool | 0 or 1
0: disable the derivative works detection
1: enable the derivative works detection
|
| music\_detection | Bool | 0 or 1
0: disable music/speech detection
1: enable music/speech detection
|
| ai\_detection | Bool | 0 or 1
0: disable ai detection
1: enable ai detection
|
{% tabs %}
{% tab title="201: Created " %}
````json
```json
{
"data": {
"id": 123456,
"uid": 123,
"region": "eu-west-1",
"name": "container name",
"buckets": [
{
"id": 23,
"name": "ACRCloud Music",
"type": "ACRCloudFile",
"metadata_template": null
}
],
"audio_type": "linein",
"num": 1,
"size": 14,
"policy": {
"type": "traverse",
"interval": 0,
"rec_length": 10,
"ai_detection": 1,
"deepright":true
},
"engine": 1,
"callback_url": null,
"created_at": "2023-04-28T07:53:40.000000Z",
"updated_at": "2023-04-28T07:53:40.000000Z"
}
}
```
````
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Python" %}
```python
import requests
url = "https://api-v2.acrcloud.com/api/fs-containers"
payload={
"name":"test",
"region":"eu-west-1",
"buckets":[8881,8882,"ACRCloud Music"],
"audio_type":"linein",
"engine":1,
"policy":{"type":"traverse", "interval":0, "rec_length":10}
}
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, json=payload)
print(response.text)
```
{% endtab %}
{% endtabs %}
## Get all the containers
`GET` `https://api-v2.acrcloud.com/api/fs-containers`
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization\* | String | Bearer your\_token |
| Content-Type | String | application/json |
#### Query Parameters
| Name | Type | Description |
| ------ | ------ | ------------------------------------------------------------------------------------ |
| region | String | list the continers in the region.
eu-west-1
us-west-2
ap-southeast-1
|
| name | String | search by name |
{% tabs %}
{% tab title="200: OK " %}
{% endtab %}
{% endtabs %}
## Update a container
`PUT` `https://api-v2.acrcloud.com/api/fs-containers/:container_id`
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization\* | String | Bearer your\_token |
| Content-Type | String | application/json |
#### Request Body
| Name | Type | Description |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | String | Your container name |
| audio\_type | String | linein or recorded. Default is linein
linein: Audio of original file or stream without noise
recorded: Audio captured via microphone or noisy audio files
|
| buckets | Array | The project detects content from the buckets. The format is bucket id/name array. For example:
\[8881,8882,"ACRCloud Music"]
|
| engine | Number | 1:Audio Fingerprinting
2:Cover Songs
3:Audio Fingerprinting & Cover songs
4:Speech to Text
|
| policy | JSON | {"type":"traverse", "interval":0, "rec\_length:10}
or
{"type":"points", "points":3}
|
| callback\_url | String | Result webhook url |
| callback\_sign\_secret | JSON | {"kid":"xx","secret":"xxxx"} |
| deepright | Bool | 0 or 1
0: disable the derivative works detection
1: enable the derivative works detection
|
| music\_detection | Bool | 0 or 1
0: disable music/speech detection
1: enable music/speech detection
|
| ai\_detection | Bool | 0 or 1
0: disable ai detection
1: enable ai detection
|
{% tabs %}
{% tab title="Python" %}
```python
import requests
url = "https://api-v2.acrcloud.com/api/fs-containers/123456"
payload={
"name":"test",
"buckets":["ACRCloud Music"],
"audio_type":"linein",
"engine":1,
"policy":{"type":"traverse", "interval":0, "rec_length":10},
"deepright":1
}
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.(url, headers=headers, json=payload)
print(response.text)
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="200: Ok " %}
````json
```json
{
"data": {
"id": 123456,
"uid": 123,
"region": "eu-west-1",
"name": "container name",
"buckets": [
{
"id": 23,
"name": "ACRCloud Music",
"type": "ACRCloudFile",
"metadata_template": null
}
],
"audio_type": "linein",
"num": 1,
"size": 14,
"policy": {
"type": "traverse",
"interval": 0,
"rec_length": 10,
"ai_detection": 1,
"deepright":true
},
"engine": 1,
"callback_url": null,
"created_at": "2023-04-28T07:53:40.000000Z",
"updated_at": "2023-04-28T07:53:40.000000Z"
}
}
```
````
{% endtab %}
{% endtabs %}
## Show one container
`GET` `https://api-v2.acrcloud.com/api/fs-containers/:container_id`
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization\* | String | Bearer your\_token |
| Content-Type | String | application/json |
{% tabs %}
{% tab title="200: OK " %}
```
{
"data": {
"id": 123456,
"uid": 123,
"region": "eu-west-1",
"name": "container name",
"buckets": [
{
"id": 23,
"name": "ACRCloud Music",
"type": "ACRCloudFile",
"metadata_template": null
}
],
"audio_type": "linein",
"num": 1, //the number of the files in the container
"size": 14, //the total duration(seconds) of the uploaded files in this container
"policy": {
"type": "traverse",
"interval": 0,
"rec_length": 10
},
"engine": 1,
"callback_url": null,
"created_at": "2023-04-28T07:53:40.000000Z",
"updated_at": "2023-04-28T07:53:40.000000Z"
}
}
```
{% endtab %}
{% endtabs %}
## Delete one container
`DELETE` `https://api-v2.acrcloud.com/api/fs-containers/:container_id`
#### Path Parameters
| Name | Type | Description |
| ----------------------------------------------- | ------ | ---------------- |
| container\_id\* | Number | The Container ID |
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization\* | String | Bearer your\_token |
| Content-Type | String | application/json |
{% tabs %}
{% tab title="204: No Content " %}
```
```
{% endtab %}
{% endtabs %}
# FsFiles
## List the files and results
`GET` `https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/:container_id/files`
This endpoint will not show the youtube channels/playlists results.\
Please replace `{ContainerRegion} with`the region of your FS Container which is one of the following regions.\
Container Regions:\
eu-west-1,us-west-2,ap-southeast-1
#### Path Parameters
| Name | Type | Description |
| ------------- | ------ | ---------------- |
| container\_id | number | The container id |
#### Query Parameters
| Name | Type | Description |
| ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| page | number | The page number |
| per\_page | number | The results number per page |
| search | string | Search by name or URI |
| with\_result | number | 1:list the files with results.
0:will not list the results (default)
|
| state | String | 0:processing
1:Ready (Recognize results from a file.)
-1: No results (No results were recognized from the file.)
-2,-3: Error
|
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="Curl" %}
```
curl --location --request GET 'https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/:your_container_id/files?page=1&per_page=20' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YourAccessToken'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/:your_container_id/files?page=1&per_page=20"
payload={}
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
{% endtab %}
{% endtabs %}
## Response descriptions
| Field Name | Type | Description |
|---|
| id | String | The id of the file |
| uid | Integer | The id of the acrcloud console account |
| cid | Integer | The id of the fs container |
| name | String | The name of the file |
| duration | Integer | The duration of the audio file |
| uri | String | The uri of the file.
if the data_type is audio/fingerprint
format: audio:file_name
if the data_type is audio_url
format: audio_url:url_path
if the data_type is platforms, such as youtube, twitter, tiktok...
format: platform:video:platform_id
youtube:video:7wtfhZwyrcc |
| data_type | String | audio: upload the audio file to the container
fingerprint: upload the acrcloud fingerprint to the container
audio_url: upload the http/https/ftp url to the container
platforms: upload the platform url, such as https://www.youtube.com/watch?v=t3MWVt4GKy8 |
| engine | Integer | What engine was used to recognize this file?
1: audio fingerprint
2: cover song identification
3: audio fingerprint & cover song identification
4: Speech recognition (STT)
5: AI Music Detection |
| count | Integer | This field is temporarily not in use. |
| state | Integer | Current state of the document:
0:processing
1:Ready (Recognize results from a file.)
-1: No results (No results were recognized from the file.)
-2,-3: Error |
| total | Integer | This field is temporarily not in use.
The total sub-files does this file contains |
| results | JSON | {
"music":[], //audio fingerprint music results
"cover_songs":[], // cover songs results
"custom_files":[], // audio fingerprint custom files matched results
"speech":[], //STT results
"music_speech":[] // music/speech detection results. "ai_detection":[] // AI music detection results.
} |
| created_at | String | The creation time(UTC+0) of the file |
| updated_at | String | The update time(UTC+0) of the file |
| deepright | Bool | This field indicates whether Derivative Works Detection is enabled. |
{% tabs %}
{% tab title="200 Successfully retrieved." %}
```
{
"data":[
{
"id":"fd0cbc13-bb69-41ed-abbb-1ed6f25c3b02",
"uid":19,
"cid":10005,
"name":"Camilo - Millones (Official Video)",
"duration":222,
"uri":"youtube:video:krP539YBF7U",
"data_type":"youtube",
"engine":1,
"count":1,
"state":1,
"created_at":"2021-04-08T10:23:29.000000Z",
"updated_at":"2021-04-23T02:58:04.000000Z",
"total":1,
"deepright":False, //True:enabled the "Derivative Works Detection"
"music_detected":1, //0:Unknown, 1: Music or Music with speech, 2: Others
"results":{
"music_speech": [
{
"start": 0,
"end": 222,
"label": "m" //m:Music, ms:Music & Speech, s:Speech, o:Others
}
],
"ai_detection": [
{
"start": 0,
"end": 249.74,
"prediction": "human",
"likely_source": "Human",
"ai_probability": 26.97,
"duration": 249.74,
"source_probabilities": [
{
"source": "suno",
"probability": 8.3
},
{
"source": "udio",
"probability": 9
},
{
"source": "sonauto",
"probability": 5
},
{
"source": "mureka",
"probability": 5.3
},
{
"source": "riffusion",
"probability": 5.3
}
]
}
],
"music":[
{
"offset":0,
"played_duration":220,
"type":"traverse",
"result":{
"album":{
"name":"Mis Manos"
},
"play_offset_ms":19780,
"sample_begin_time_offset_ms":0,
"contributors":{
"composers":[
"Camilo Echeverry",
"Édgar Barrera"
],
"lyricists":[
"Camilo Echeverry",
"Édgar Barrera"
]
},
"title":"Millones",
"result_from":3,
"release_date":"2021-03-04",
"sample_end_time_offset_ms":9440,
"genres":[
{
"name":"Latin Pop"
}
],
"label":"SME - Sony Music Latin",
"db_end_time_offset_ms":19300,
"score":100,
"db_begin_time_offset_ms":9860,
"artists":[
{
"name":"Camilo"
}
],
"duration_ms":221000,
"external_ids":{
"isrc":"USSD12100051",
"upc":"886449088867"
},
"acrid":"300f34d92ec1f3a7397bb2bb9cddf884",
"external_metadata":{
"spotify":{
"album":{
"name":"Mis Manos"
},
"track":{
"name":"Millones",
"id":"3YAnNBdk0uHyakXXzMbNJq"
},
"artists":[
{
"name":"Camilo"
}
]
},
"deezer":{
"album":{
"name":""
},
"track":{
"name":"Millones",
"id":"1260566282"
},
"artists":[
{
"name":"Camilo"
}
]
}
}
}
}
]
}
},
{
"id":"5c2cfaa2-6024-4775-ac24-1aa7b4786c86",
"uid":19,
"cid":10005,
"name":"Lil Tjay - Love Hurts (Feat. Toosii) [Official Video]",
"duration":247,
"uri":"youtube:video:V-IDVYH3YjA",
"data_type":"youtube",
"engine":1,
"count":1,
"state":1,
"created_at":"2021-04-08T08:26:55.000000Z",
"updated_at":"2021-04-23T02:58:04.000000Z",
"total":1,
"music_detected":1
"results":{
"music_speech": [
{
"start": 0,
"end": 247,
"label": "m"
}
],
"music":[
{
"offset":14,
"played_duration":5,
"type":"traverse",
"result":{
"album":{
"name":"my ex called"
},
"play_offset_ms":6440,
"sample_begin_time_offset_ms":4260,
"title":"my ex called",
"result_from":3,
"release_date":"2020-02-21",
"sample_end_time_offset_ms":8860,
"label":"Thrill$",
"db_end_time_offset_ms":4600,
"score":100,
"db_begin_time_offset_ms":0,
"artists":[
{
"name":"Thrill$"
}
],
"duration_ms":168920,
"external_ids":{
"isrc":"QZJG52083365",
"upc":"194923628486"
},
"acrid":"269e27604f4be4c3167fc3751f5551c3",
"external_metadata":{
"deezer":{
"album":{
"name":""
},
"track":{
"name":"Havit",
"id":"1098021672"
},
"artists":[
{
"name":"Of_mannyg"
}
]
}
}
}
},
{
"offset":24,
"played_duration":14,
"type":"traverse",
"result":{
"album":{
"name":"Lost Files"
},
"play_offset_ms":5340,
"sample_begin_time_offset_ms":4080,
"title":"In the Streets",
"result_from":1,
"release_date":"2020-10-26",
"sample_end_time_offset_ms":9260,
"label":"Hitta Huncho",
"db_end_time_offset_ms":5180,
"score":100,
"db_begin_time_offset_ms":0,
"artists":[
{
"name":"Hitta Huncho"
}
],
"duration_ms":160940,
"external_ids":{
"isrc":"TCAFE2056515",
"upc":"859742903298"
},
"acrid":"e63ee358a9357a1e181cd8ce858d78fd",
"external_metadata":{
"deezer":{
"album":{
"name":""
},
"track":{
"name":"In the Streets",
"id":"1131507852"
},
"artists":[
{
"name":"Hitta Huncho"
}
]
}
}
}
},
{
"offset":30,
"played_duration":209,
"type":"traverse",
"result":{
"album":{
"name":"Destined 2 Win"
},
"play_offset_ms":25880,
"sample_begin_time_offset_ms":0,
"title":"Love Hurts",
"result_from":1,
"release_date":"2021-04-02",
"sample_end_time_offset_ms":8200,
"genres":[
{
"name":"Hip Hop"
}
],
"label":"Columbia",
"db_end_time_offset_ms":24100,
"score":100,
"db_begin_time_offset_ms":15900,
"artists":[
{
"name":"Lil Tjay"
}
],
"duration_ms":222100,
"external_ids":{
"isrc":"USSM12101539",
"upc":"886449173587"
},
"acrid":"d981bc8a8a55b06d15d5ea0f4957873c",
"external_metadata":{
"spotify":{
"album":{
"name":"Destined 2 Win"
},
"track":{
"name":"Love Hurts (feat. Toosii)",
"id":"2ULQtFHTzUK0DqcqWUlXxw"
},
"artists":[
{
"name":"Lil Tjay"
},
{
"name":"Toosii"
}
]
}
}
}
}
]
}
}
],
"links":{
"first":"https://ap-api-v2.acrcloud.com/api/fs-containers/10005/files?page=1",
"last":"https://ap-api-v2.acrcloud.com/api/fs-containers/10005/files?page=1",
"prev":null,
"next":null
},
"meta":{
"current_page":1,
"from":1,
"last_page":1,
"path":"https://ap-api-v2.acrcloud.com/api/fs-containers/10005/files",
"per_page":"20",
"to":2,
"total":2
}
}
```
{% endtab %}
{% endtabs %}
## Upload a file or platform web URL
`POST` `https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/:container_id/files`
Please replace `{ContainerRegion} with`the region of your FS Container which is one of the following regions.\
Container Regions:\
eu-west-1,us-west-2,ap-southeast-1
#### Path Parameters
| Name | Type | Description |
| ----------------------------------------------- | ------ | ---------------- |
| container\_id\* | number | The container id |
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ------------ |
| Authorization\* | string | Bearer token |
#### Request Body
| Name | Type | Description |
| -------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| file | object | The audio or fingerprint file, The audio/fingerprint file size needs to be less than 500MB. |
| data\_type\* | string | audio: Upload an audio file
fingerprint: Upload a fingerprint file
platforms: platforms url. Currently, supported platforms are Youtube,Twitter, Tiktok, Vimeo, Brightcove...etc. You can post the platform's web url to this endpoint.
audio\_url: Downloadable audio url.
isrc: Supports posting ISRC data to the container. This data type is available when the container has derivative works detection or AI music detection enabled.
|
| url | string | If the datatype is platforms or audio\_url, you need to add this parameter.
For example:
|
| name | string | If you do not pass this parameter, we will use the file path or url path as the file name. |
| isrc | string | If you set the data\_type is isrc, then this field input the value of the isrc. |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"uid": 19,
"cid": 10005,
"name": "886443683402_US4D80623007.lo",
"duration": 159.56,
"uri": "audio:886443683402_US4D80623007.lo",
"data_type": "audio",
"method": 1,
"count": 0,
"state": 0,
"updated_at": "2021-04-23T07:33:21.000000Z",
"created_at": "2021-04-23T07:33:21.000000Z",
"id": "9d0f2c36-0265-46c2-b3e4-c0c2d0b9eb92",
"total": 1
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl (audio)" %}
```
curl --location --request POST 'https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/10005/files' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--form 'file=@"/Users/olym/Downloads/886443683402_US4D80623007.mp3"' \
--form 'data_type="audio"'
```
{% endtab %}
{% tab title="Curl (platforms)" %}
```
curl --location --request POST 'https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/10005/files' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{"data_type":"platforms", "url":"https://twitter.com/i/status/1439937773885079552"}'
```
{% endtab %}
{% tab title="Python" %}
{% code overflow="wrap" lineNumbers="true" %}
```python
import requests
url = "https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/10005/files"
payload={'data_type': 'audio'}
files=[
('file',('886443683402_US4D80623007.mp3',open('886443683402_US4D80623007.mp3','rb'),'application/octet-stream'))
]
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer token'
}
response = requests.request("POST", url, headers=headers, data=payload, files=files)
```
{% endcode %}
{% endtab %}
{% tab title="Python(platforms)" %}
```
import requests
url = "https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/10005/files"
payload={
'data_type': 'platforms',
'url':'https://www.youtube.com/watch?v=d_xYl5hpiRs'
}
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, json=payload)
```
{% endtab %}
{% tab title="PHP" %}
```php
'https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/10005/files',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => array('file'=> new CURLFILE('886443683402_US4D80623007.lo'),'data_type' => 'fingerprint'),
CURLOPT_HTTPHEADER => array(
'Accept: application/json',
'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiI2IiwianRpIjoiZGMzNjIyOThhMDAyN2NmZDMzZGU3MjBhYThhY2I0MTgyMzJhN2I5ZTA4MzdjNTI0M2UxODIxYzcwMTA5NDIwZTg0ZGJhY2Q4YTRhZWM0YzAiLCJpYXQiOjE2MTg4MjA1NTAuMDA2OTYzLCJuYmYiOjE2MTg4MjA1NTAuMDA2OTY3LCJleHAiOjE2NTAzNTY1NDkuOTkwNTQxLCJzdWIiOiIxOSIsInNjb3BlcyI6WyIqIl19.G7L5T2fQljhK2D1za669Q3cIIbyBT0oE8Z_IWQyL0sofZvIOYymVqW55w6b_nX6emkJj7JfylAI7q7-CVxXUN4tRcJCv9-AxFprhQubKvy59_6B5jd38jsOGHdlmMN5x7Mt3xl9WUPd1ODFg6Vqp3tR3nQ9J9eqUjrZgu54Yyx-1_gekBx87GCvcJxfmiDTBmr8J4Ze5099W_Bsj5UHGUb1X-GhNxVzfTFranTsvSEFDEA5jrBvNGIRkvqMUCx4jK7sJstlnlvTUmJ6WK0owl946ULiJhPe5jlM2_CKDckw81Ri6ecV1zAOWncTWi1Oa5qUkpEVf6pBtzk4_OLLjWUZ3MRz7xO2BiFYTuWxaQKNL9W4RhWbsf'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
```
{% endtab %}
{% endtabs %}
## Presigned Upload
Upload files directly to S3 using a presigned URL, bypassing the API server.\
Recommended for large files (>100MB) to avoid timeout issues.
This is a three-step process:
1. **Get a presigned URL** — Request a temporary S3 upload URL from the API.
2. **Upload to S3** — PUT the file directly to S3 using the presigned URL.
3. **Submit file metadata** — Notify the API that the file has been uploaded to trigger recognition.
### Step 1: Get Presigned Upload URL
`GET` `https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/:container_id/presigned-upload`
#### Query Parameters
| Name | Location | Required | Description |
| -------------- | -------- | -------- | --------------------------------- |
| `filename` | query | No | File name (e.g. `song.mp3`) |
| `content_type` | query | No | MIME type (default: `audio/mpeg`) |
#### Headers
| Name | Location | Required | Description |
| --------------- | -------- | -------- | ----------------------- |
| `Authorization` | header | Yes | `Bearer {access_token}` |
#### Example
```bash
curl -X GET "https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/{container_id}/presigned-upload?filename=song.mp3" \
-H "Authorization: Bearer {access_token}"
```
#### Response
```json
{
"data": {
"presigned_url": "https://{bucket-name}.s3.{region}.amazonaws.com/fs/queue/abc123.mp3?X-Amz-...",
"key": "fs/queue/abc123.mp3",
"method": "PUT",
"headers": {
"Content-Type": "audio/mpeg"
},
"expires_in": 3600,
"file_id": "abc123-def456-...",
"usage": "PUT the file to presigned_url, then POST /{cid}/files with {data_type:'audio', key:'', filename:''}"
}
}
```
| Field | Description |
| --------------- | ----------------------------------------------------- |
| `presigned_url` | Temporary S3 URL for direct upload (valid for 1 hour) |
| `key` | S3 object key, used in Step 3 |
| `method` | HTTP method for upload (`PUT`) |
| `headers` | Required headers for the PUT request |
| `expires_in` | URL expiration time in seconds |
| `file_id` | Generated file ID |
### Step 2: Upload File to S3
`PUT` `{presigned_url}`
#### Headers
| Header | Required | Description |
| -------------- | -------- | ----------------------------------------- |
| `Content-Type` | Yes | Must match the `content_type` from Step 1 |
#### Example
```bash
curl -X PUT "https://{bucket-name}.s3.{region}.amazonaws.com/fs/queue/abc123.mp3?X-Amz-..." \
-H "Content-Type: audio/mpeg" \
--data-binary @song.mp3
```
> **Note:** Do not send the `Authorization` header to S3. The presigned URL contains all necessary credentials.
### Step 3: Submit File Metadata
After the file has been uploaded to S3, submit the file metadata to trigger the recognition process.
`POST` `https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/:container_id/files`
#### Headers
| Name | Location | Required | Description |
| --------------- | -------- | -------- | ----------------------- |
| `Authorization` | header | Yes | `Bearer {access_token}` |
| `Content-Type` | header | Yes | `application/json` |
#### Request Body
```json
{
"data_type": "audio",
"key": "fs/queue/abc123.mp3",
"filename": "song.mp3"
}
```
| Field | Required | Description |
| ----------- | -------- | ---------------------------------- |
| `data_type` | Yes | Must be `audio` |
| `key` | Yes | S3 object key from Step 1 response |
| `filename` | Yes | Original file name |
#### Example
```bash
curl -X POST "https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/{container_id}/files" \
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: application/json" \
-d '{
"data_type": "audio",
"key": "fs/queue/abc123.mp3",
"filename": "song.mp3"
}'
```
#### Response (201 Created)
```json
{
"data": {
"file_id": "abc123-def456-...",
"name": "song.mp3",
"state": 0,
"duration": 0,
...
}
}
```
### Full Example (Python)
```python
import requests
BASE_URL = "https://api-{ContainerRegion}.acrcloud.com/api"
ACCESS_TOKEN = "***"
CONTAINER_ID = 0 # Replace with your own container ID
FILE_PATH = "song.mp3"
headers = {"Authorization": f"Bearer {ACCESS_TOKEN}"}
# Step 1: Get presigned URL
resp = requests.get(
f"{BASE_URL}/fs-containers/{CONTAINER_ID}/presigned-upload",
params={"filename": "song.mp3"},
headers=headers
)
data = resp.json()["data"]
presigned_url = data["presigned_url"]
s3_key = data["key"]
print(f"Presigned URL obtained, key={s3_key}")
# Step 2: Upload file directly to S3
with open(FILE_PATH, "rb") as f:
requests.put(
presigned_url,
headers={"Content-Type": "audio/mpeg"},
data=f
)
print("File uploaded to S3")
# Step 3: Submit metadata to trigger recognition
resp = requests.post(
f"{BASE_URL}/fs-containers/{CONTAINER_ID}/files",
headers={
**headers,
"Content-Type": "application/json"
},
json={
"data_type": "audio",
"key": s3_key,
"filename": "song.mp3"
}
)
print(f"File submitted, status={resp.status_code}")
print(resp.json())
```
### Comparison
| | Direct Upload (POST /files) | Presigned Upload |
| -------------- | --------------------------------- | ---------------------- |
| Max file size | Limited by Nginx/gunicorn timeout | No limit (S3 direct) |
| Server load | High (bandwidth + memory) | None (bypasses server) |
| Timeout risk | High for large files | Low |
| URL expiration | N/A | 1 hour |
| Complexity | Simple (1 request) | 3 requests |
### Error Handling
| Status | Error | Solution |
| ------ | --------------------- | --------------------------------------------- |
| 401 | Unauthorized | Check access token |
| 403 | Forbidden | Check container permissions |
| 404 | Container not found | Verify container ID |
| 410 | Expired presigned URL | Request a new URL (Step 1) |
| 502 | Upload timeout | Use presigned upload instead of direct upload |
## Show the one file or multiple files's results
`GET` `https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/:container_id/files/:file_ids`
Suit for getting the youtube channels/playlists results\
Please replace `{ContainerRegion} with`the region of your FS Container which is one of the following regions.\
Container Regions:\
eu-west-1,us-west-2,ap-southeast-1
#### Path Parameters
| Name | Type | Description |
| ------------- | ------ | ------------------------------------------------------------------------------ |
| container\_id | number | The container id |
| file\_ids | string | The file ids, if you want to get multiple files, separate file IDs with comma. |
#### Query Parameters
| Name | Type | Description |
| --------- | ------ | --------------------------- |
| page | string | The page number |
| per\_page | string | The results number per page |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
````
```json
{
"data": [
{
"id": "e1cc5a16-e7b2-4261-9ab8-c20e1db70ac0",
"uid": 1,
"cid": 11655,
"name": "/vod/video-3/01G6D3Z2SSDEDEGHP9ZSX8KC20/audio.mp4",
"duration": 7,
"uri": "audio_url:/01G6D3Z2SSDEDEGHP9ZSX8KC20/audio.mp4",
"url": "https://test.com/01G6D3Z2SSDEDEGHP9ZSX8KC20/audio.mp4",
"data_type": "audio_url",
"engine": 1,
"count": 1,
"state": 1,
"subscribed": 0,
"detail": "",
"created_at": "2022-07-06T03:50:33.000000Z",
"updated_at": "2022-07-06T03:50:33.000000Z",
"total": 1,
"results": {
"ai_detection": [
{
"start": 0,
"end": 249.74,
"prediction": "human",
"likely_source": "Human",
"ai_probability": 26.97,
"duration": 249.74,
"source_probabilities": [
{
"source": "suno",
"probability": 8.3
},
{
"source": "udio",
"probability": 9
},
{
"source": "sonauto",
"probability": 5
},
{
"source": "mureka",
"probability": 5.3
},
{
"source": "riffusion",
"probability": 5.3
}
]
}
],
"music": [
{
"played_duration": 7,
"offset": 0,
"type": "traverse",
"result": {
"album": {
"id": "3RQQmkQEvNCY4prGKE6oc5",
"name": "Un Verano Sin Ti"
},
"play_offset_ms": 87400,
"genres": [
{
"name": "Latin"
}
],
"title": "Efecto",
"result_from": 3,
"release_date": "2022-05-06",
"sample_end_time_offset_ms": 6160,
"sample_begin_time_offset_ms": 0,
"label": "Rimas Entertainment LLC",
"duration_ms": 213061,
"score": 100,
"db_begin_time_offset_ms": 80720,
"artists": [
{
"id": "4q3ewBCX7sLwd24euuV69X",
"name": "Bad Bunny"
}
],
"db_end_time_offset_ms": 86880,
"external_ids": {
"isrc": "QM6MZ2214884",
"upc": "196626945068"
},
"acrid": "fd4e72b6dd70cdc0dde7f1f81a5c4df3",
"external_metadata": {
"musicbrainz": {
"track": {
"id": "782ee794-afb3-4adb-a1d7-c6fdc1d945de"
}
},
"spotify": {
"track": {
"id": "5Eax0qFko2dh7Rl2lYs3bx",
"name": "Efecto"
},
"album": {
"name": "Un Verano Sin Ti"
},
"artists": [
{
"name": "Bad Bunny"
}
]
},
"deezer": {
"track": {
"id": "1741494377",
"name": "Efecto"
},
"album": {
"name": "Un Verano Sin Ti"
},
"artists": [
{
"name": "Bad Bunny"
}
]
},
"youtube": {
"vid": "yO-XR4qXm1k"
}
}
}
}
]
}
}
]
}
```
````
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```
curl --location --request GET 'https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/:your_container_id/files/f60c40d8-f35e-488e-bca4-105d85b080dc' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YourAccessToken'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/:your_container_id/files/f60c40d8-f35e-488e-bca4-105d85b080dc"
payload={}
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
{% endtab %}
{% endtabs %}
## Delete the files
`DELETE` `https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/:container_id/files/:ids`
Please replace `{ContainerRegion} with`the region of your FS Container which is one of the following regions.\
Container Regions:\
eu-west-1,us-west-2,ap-southeast-1
#### Path Parameters
| Name | Type | Description |
| ------------- | ------ | ------------------------------- |
| container\_id | string | The container id |
| ids | string | The files ids, seperated by "," |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="204 " %}
```
```
{% endtab %}
{% endtabs %}
## Rescan the files
`PUT` `https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/:container_id/files/:file_id/rescan`
Please replace `{ContainerRegion} with`the region of your FS Container which is one of the following regions.\
Container Regions:\
eu-west-1,us-west-2,ap-southeast-1
#### Path Parameters
| Name | Type | Description |
| ------------- | ------ | ----------------------------- |
| container\_id | String | The container id |
| file\_ids | String | The file ids, separate by ',' |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | String | Bearer token |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
// Response
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
{% code overflow="wrap" lineNumbers="true" %}
```shell
curl --location --request PUT 'https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/10005/files/fd0cbc13-bb69-41ed-abbb-1ed6f25c3b02/rescan' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endcode %}
{% endtab %}
{% tab title="Python" %}
{% code overflow="wrap" lineNumbers="true" %}
```python
import requests
url = "https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/10005/files/fd0cbc13-bb69-41ed-abbb-1ed6f25c3b02/rescan"
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer token'
}
response = requests.request("PUT", url, headers=headers)
```
{% endcode %}
{% endtab %}
{% endtabs %}
## Post result and state with json format to callback url
`POST` `https://callback-url.com/path`
#### Request Body
| Name | Type | Description |
| ------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| file\_id\* | String | The file id |
| cid\* | String | The container id |
| state\* | String | 1:Ready (Recognize results from a file.)
-1: No results (No results were recognized from the file.)
-2,-3: Error
|
| results | String | if the state = 1, the results will be posted to the callback url
The format is:
{
"music":\[{},{}...],
"custom\_files":\[{},{},...],
"cover\_files":\[{},{},...]
}
|
| name | String | the file name |
```python
import requests
post_data = {
'file_id':"c7331194-ccbe-4c3f-8e82-40d7b8358993",
'state':1,
'cid':1000,
'name': "FILE Name",
'results': {
"music":[
{
"played_duration":164,
"type":"traverse",
"result":{
"album":{
"name":"Indie Brit Romance"
},
"play_offset_ms":10000,
"sample_begin_time_offset_ms":0,
"title":"Broken Skies 3",
"result_from":1,
"release_date":"2016-06-28",
"sample_end_time_offset_ms":9280,
"genres":[
{
"name":"Indie"
},
{
"name":"Singer"
},
{
"name":"Songwriter"
}
],
"label":"Audio Network",
"duration_ms":167000,
"score":100,
"db_begin_time_offset_ms":0,
"artists":[
{
"name":"Bob Bradley"
},
{
"name":"Matt Parker"
}
],
"db_end_time_offset_ms":9280,
"external_ids":{
"isrc":"GBFFM1621637"
},
"acrid":"e8b02eab3fd1d2745f460fb608b7b5c1",
"external_metadata":[
]
},
"offset":0
}]
}
r = requests.post(callback_url, json=post_data, timeout=3)
```
## Download the integrated FS results
`GET` [https://api-{ContainerRegion}.acrcloud.com](https://ap-api-v2.acrcloud.com)/api/fs-containers/:container\_id/reports
The entire container fs results will be downloaded if no query parameter is specified.\
Please replace `{ContainerRegion} with`the region of your FS Container which is one of the following regions.\
Container Regions:\
eu-west-1,us-west-2,ap-southeast-1
**Headers**
| Name | Value |
| ------------- | ------------------ |
| Content-Type | `application/json` |
| Authorization | `Bearer ` |
#### Path Parameters
| Name | Type | Description |
| ------------- | ------ | ------------------- |
| container\_id | string | The fs container id |
Query Parameters
| Name | Type | Description |
| ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ids | string | filter by file ids, separate by commas |
| start\_date | datetime | filter by start date, If filtered by time, both start\_date and end\_date need to exist simultaneously.
format: YYYY-MM-DD
|
| end\_date | datetime | filter by end date, If filtered by time, both start\_date and end\_date need to exist simultaneously.
format:YYYY-MM-DD
|
| type | string | values: all, merged, music, cover\_songs, custom.
default value: all (Download all results and compress them into a zip file, which needs to be unzipped to access the results.）
merged: csv content with merged all the results.
music: csv content with music result
cover\_songs: csv content with cover\_songs results
custom: csv content with the results from customer's buckets
|
Examples
{% tabs %}
{% tab title="Curl" %}
```sh
curl --location 'https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/CONTIANER_ID/reports?ids=72eb3a04-5a49-4b5e-aab0-4bdd8f5fff6d' \
--header 'Authorization: Bearer YOUR_TOKEN' -o fs_report.zip
curl --location 'https://api-{ContainerRegion}.acrcloud.com/api/fs-containers/CONTIANER_ID/reports?type=merged&ids=72eb3a04-5a49-4b5e-aab0-4bdd8f5fff6d' \
--header 'Authorization: Bearer YOUR_TOKEN' -o fs_report.csv
```
{% endtab %}
{% endtabs %}
# Metadata
# Music
An example of music metadata for Audio & Video Recognition project
### JSON structure
```json
{
"music": [
{
"offset": 14,
"played_duration": 5,
"type": "traverse",
"result": {
"album": {
"name": "my ex called"
},
"play_offset_ms": 6440,
"sample_begin_time_offset_ms": 4260,
"title": "my ex called",
"result_from": 3,
"release_date": "2020-02-21",
"sample_end_time_offset_ms": 8860,
"label": "Thrill$",
"db_end_time_offset_ms": 4600,
"score": 100,
"db_begin_time_offset_ms": 0,
"artists": [
{
"name": "Thrill$"
}
],
"duration_ms": 168920,
"external_ids": {
"isrc": "QZJG52083365",
"upc": "194923628486"
},
"acrid": "269e27604f4be4c3167fc3751f5551c3",
"external_metadata": {
"deezer": {
"album": {
"name": ""
},
"track": {
"name": "Havit",
"id": "1098021672"
},
"artists": [
{
"name": "Of_mannyg"
}
]
}
}
}
},
{
"offset": 24,
"played_duration": 14,
"type": "traverse",
"result": {
"album": {
"name": "Lost Files"
},
"play_offset_ms": 5340,
"sample_begin_time_offset_ms": 4080,
"title": "In the Streets",
"result_from": 1,
"release_date": "2020-10-26",
"sample_end_time_offset_ms": 9260,
"label": "Hitta Huncho",
"db_end_time_offset_ms": 5180,
"score": 100,
"db_begin_time_offset_ms": 0,
"artists": [
{
"name": "Hitta Huncho"
}
],
"duration_ms": 160940,
"external_ids": {
"isrc": "TCAFE2056515",
"upc": "859742903298"
},
"acrid": "e63ee358a9357a1e181cd8ce858d78fd",
"external_metadata": {
"deezer": {
"album": {
"name": ""
},
"track": {
"name": "In the Streets",
"id": "1131507852"
},
"artists": [
{
"name": "Hitta Huncho"
}
]
}
}
}
},
{
"offset": 30,
"played_duration": 209,
"type": "traverse",
"result": {
"album": {
"name": "Destined 2 Win"
},
"play_offset_ms": 25880,
"sample_begin_time_offset_ms": 0,
"title": "Love Hurts",
"result_from": 1,
"release_date": "2021-04-02",
"sample_end_time_offset_ms": 8200,
"genres": [
{
"name": "Hip Hop"
}
],
"label": "Columbia",
"db_end_time_offset_ms": 24100,
"score": 100,
"db_begin_time_offset_ms": 15900,
"artists": [
{
"name": "Lil Tjay"
}
],
"duration_ms": 222100,
"external_ids": {
"isrc": "USSM12101539",
"upc": "886449173587"
},
"acrid": "d981bc8a8a55b06d15d5ea0f4957873c",
"external_metadata": {
"spotify": {
"album": {
"name": "Destined 2 Win"
},
"track": {
"name": "Love Hurts (feat. Toosii)",
"id": "2ULQtFHTzUK0DqcqWUlXxw"
},
"artists": [
{
"name": "Lil Tjay"
},
{
"name": "Toosii"
}
]
}
},
"distributors":["Sony Music Entertainment"]
}
}
]
}
```
### Metadata fields
| Name | Description |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| music | Music fields |
| acrid | ACRCloud unique identifier |
| timestamp\_utc | Server time of sending results, Timestamp of the song started for custom monitoring, UTC time zone |
| title | Track title |
| album | Album fields |
| id | Identifier of the artists , album or 3rd parties fields |
| name | Name of the artists or album |
| artists | Artists fields |
| duration\_ms | Duration of the track in millisecond |
| play\_offset\_ms | The time position of the audio/song being played (millisecond) |
| external\_ids | External standard code |
| isrc | ISRC code |
| upc | UPC code |
| external\_metadata | External 3rd party IDs and metadata |
| track | Track fields |
| genres | Genres fields |
| label | Music label name |
| release\_date | Release data of the track, format:YYYY-MM-DD |
| spotify | Spotify fields |
| deezer | Deezer fields |
| lyricfind | LyricFind fields |
| lfid | LyricsFind's lyric ID |
| youtube | YouTube fields |
| vid | Youtube video ID |
| musicbrainz | MusicBrainz Identifier - MBID |
| db\_begin\_time\_offset\_ms | Position of beginning of the recognition on database file (millisecond) |
| db\_end\_time\_offset\_ms | Position of end of the recognition on database file (millisecond) |
| sample\_begin\_time\_offset\_ms | Position of beginning of the recognition in sample file sent by SDK/API (millisecond) |
| sample\_end\_time\_offset\_ms | Position of end of the recognition in sample file sent by SDK/API (millisecond) |
| played\_duration | Actual duration of the track played in the streams for Broadcast Monitoring service, in second |
| score | Match confidence score. Range: 70 - 100 |
| +contributors | Contributor information for this track |
| +composers | Composers of the song |
| +lyricists | Writers of the lyrics |
| language | Language of the song, ISO 639-1 codes |
| langs | Translation into different languages. Example: \[{"code":"ru", "name":"Я твой враг"}] |
| #rights\_claim | All relevant metadata fields to determine rights owners, available territories and rights claim policy for UGC platforms. These metadata fields are for copyright compliance users only. |
| #distributor | Information of distributor for this track |
| #id | DDEX Party ID of the distributor, this ID won't change. |
| #name | Name of the distributor, This name might be changing from time to time. |
| #rights\_claim\_policy | Right policy for UGC platforms, the value options are "Monetize", "Allow", "ReportUsage" and "BlockAccess". |
| #rights\_owners | Rights owners' name, example: \[{"name":"Warner Music Group", "share\_percentage":100}] |
| #territories | Territory codes for Included territories, ISO country codes applied. |
| #excluded\_territories | Territory codes for excluded territories, ISO country codes applied. |
| #share\_percentage | Percentage of the rights share for each rights owners. |
| #release\_by\_territories | Release details by territories, indicate the release date for territories. |
| +work | Publishing metadata fields for works |
| +ISWC | ISWC code |
| +name | Name of the work |
| +creators | The creators of the work |
| +ipi | IPI code for the creator |
| +roles | The roles of the creator |
| time\_skew | Time skew refers to a temporal misalignment or timing offset between two audio signals. It means that the audio events (such as beats, notes, or spectral features) occur earlier or later in time than expected. |
| frequency\_skew | Frequency skew refers to a distortion in the frequency domain, where the spectral components of the audio are shifted upward or downward in frequency. |
{% hint style="info" %}
**Please note: Only *****ACRID,*** ***Track Title, Artists Name, Album Name***** and \*\_time\_offset\_ms fields are required, other fields are optional.**
\#fields are visible for the projects with copyright compliance option only.
+fields are visible upon request, please contact us if you need those fields.
{% endhint %}
# Custom Files
An example of custom-defined metadata for Audio & Video Recognition, Broadcast Monitoring, Hybrid Recognition and Offline Recognition projects.
### JSON structure
```bash
{
"custom_files": [
{
"offset": 0,
"played_duration": 14,
"type": "traverse",
"result": {
"bucket_id": "51",
"title": "You are beautiful",
"artist": "James",
"acrid": "5343bc191634b042622bf474ed46121a",
"audio_id": "3"
}
}
]
}
```
### Metadata fields
| Name | Description |
| --------------------------------- | ------------------------------------------------------------------------------------- |
| custom\_files | Custom uploaded file fields |
| arcid | ACRCloud unique identifier |
| title | File name |
| audio\_id | User defined identifier |
| play\_offset\_ms | Position of the recognition in the file if the file was playing (millisecond) |
| \*db\_begin\_time\_offset\_ms | Position of beginning of the recognition on database file (millisecond) |
| \*db\_end\_time\_offset\_ms | Position of end of the recognition on database file (millisecond) |
| \*sample\_begin\_time\_offset\_ms | Position of beginning of the recognition in sample file sent by SDK/API (millisecond) |
| \*sample\_end\_time\_offset\_ms | Position of end of the recognition in sample file sent by SDK/API (millisecond) |
{% hint style="info" %}
***\* fields are visible in Broadcast Monitoring service only, if you want to use these fields in recognition service, please contact us.***
**Please note: Only *****Title, ARCID, Audio\_ID***** are required fields.**
{% endhint %}
# Cover Songs
An example cover songs metadata for FS project.
```bash
{
"cover_songs": [
{
"offset": 1.71,
"played_duration": 297.32,
"type": "traverse",
"engine_type": "2",
"result": {
"title": "Carrying the Banner",
"artists": [
{
"langs": [
{
"code": "en",
"name": "Newsies Ensemble"
}
],
"name": "Newsies Ensemble",
"roles": [
"MainArtist"
]
}
],
"album": {
"name": null
},
"label": "Walt Disney Records",
"release_date": null,
"duration_ms": 373000,
"external_ids": {
"isrc": "USWD10423231"
},
"distributors": [
"UMG"
],
"external_metadata": {
"spotify": {
"track": {
"id": "0n1I8KDjS2HYeESQo4zPry"
}
},
"deezer": {
"track": {
"id": "1761602537"
}
},
"apple": {
"track": {
"id": "1440650771"
}
}
}
}
}
]
}
```
# AI Music Detection
An example of ai detection metadata for FS project.
```json
{
"ai_detection": [
{
"start": 0,
"end": 168.68,
"prediction": "ai_generated", //ai_generated,human,no_vocals
"likely_source": "Suno", //Suno,Udio,Sonauto,Mureka,Riffusion,Human,no_vocals
"ai_probability": 97.61,
"duration": 168.68,
"stem": "original", //original, vocals, accompaniment
"source_probabilities": [
{
"source": "Suno",
"probability": 96
},
{
"source": "Udio",
"probability": 0.6
},
{
"source": "Sonauto",
"probability": 0.2
},
{
"source": "Mureka",
"probability": 0.8
},
{
"source": "Riffusion",
"probability": 0.2
},
{
"source": "Seedmusic",
"probability": 0.7
},
{
"source": "Minimax",
"probability": 0.2
},
{
"source": "Elevenlabs",
"probability": 0.1
}
],
"segments": [
{
"start": 0,
"end": 168.68,
"prediction": "ai_generated",
"likely_source": "Suno",
"ai_probability": 98.64
}
],
"model_id": "lv1axtcv" // model version
},
{
"start": 0,
"end": 168.68,
"prediction": "ai_generated",
"likely_source": "Suno",
"ai_probability": 93.05,
"duration": 168.68,
"source_probabilities": [
{
"source": "Suno",
"probability": 88.3
},
{
"source": "Udio",
"probability": 1.1
},
{
"source": "Sonauto",
"probability": 0.6
},
{
"source": "Mureka",
"probability": 3.1
},
{
"source": "Rdiffusion",
"probability": 0.6
},
{
"source": "Seedmusic",
"probability": 1.2
},
{
"source": "Minimax",
"probability": 0.1
},
{
"source": "Elevenlabs",
"probability": 0.1
}
],
"stem": "vocals",
"segments": [
{
"start": 0,
"end": 156,
"prediction": "ai_generated",
"likely_source": "Suno",
"ai_probability": 96.74
},
{
"start": 156,
"end": 160,
"prediction": "ai_generated",
"likely_source": "Mureka",
"ai_probability": 61.83
},
{
"start": 160,
"end": 164,
"prediction": "human",
"likely_source": "Human",
"ai_probability": 19.3
},
{
"start": 164,
"end": 168.68,
"prediction": "ai_generated",
"likely_source": "Suno",
"ai_probability": 91.29
}
],
"model_id": "lv1axtcv"
},
{
"start": 0,
"end": 168.68,
"prediction": "ai_generated",
"likely_source": "Suno",
"ai_probability": 97.58,
"duration": 168.68,
"source_probabilities": [
{
"source": "Suno",
"probability": 96
},
{
"source": "Udio",
"probability": 0.7
},
{
"source": "Sonauto",
"probability": 0.3
},
{
"source": "Mureka",
"probability": 0.6
},
{
"source": "Rdiffusion",
"probability": 0.2
},
{
"source": "Seedmusic",
"probability": 0.6
},
{
"source": "Minimax",
"probability": 0.1
},
{
"source": "Elevenlabs",
"probability": 0.1
}
],
"stem": "accompaniment",
"segments": [
{
"start": 0,
"end": 168.68,
"prediction": "ai_generated",
"likely_source": "Suno",
"ai_probability": 98.56
}
],
"model_id": "lv1axtcv"
}
]
}
```
# Music/Speech Detection
An example of music/speech detection metadata for FS project.
```json
{
"music_speech":[
{
"start": 0,
"end": 222,
"label": "m" //m:Music, ms:Music & Speech, s:Speech, o:Others
}
]
}
```
# UCF Projects
## Create a ucf project
`POST` `https://api-v2.acrcloud.com/api/ucf-projects`
This endpoint allows you to get free cakes.
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
#### Request Body
| Name | Type | Description |
| ------ | ------ | ------------------------------------------------------ |
| name | string | The project name |
| type | string | BM or FILES, default is BM. |
| region | string | eu-west-1,us-west-2,ap-southeast-1 |
| config | object | default is {"days":3,"mini\_ms":5000,"max\_ms":300000} |
{% tabs %}
{% tab title="200 Project successfully created." %}
```
{
"data": {
"uid": 1,
"name": "test",
"region": "eu-west-1",
"type": "BM",
"config": {
"days": 3,
"min_ms": 5000,
"max_ms": 300000
},
"updated_at": "2020-12-28T04:57:13.000000Z",
"created_at": "2020-12-28T04:57:13.000000Z",
"id": 100000
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request POST 'http://127.0.0.1:8080/api/ucf-projects' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{"name":"test", "region":"eu-west-1", "type":"BM"}'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "http://127.0.0.1:8080/api/ucf-projects"
payload={"name":"test", "region":"eu-west-1", "type":"BM"}"
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiI2IiwianRpIjoiN2Y2N2NhNmE4NmMxOGZiMWZmYmVkOWM5OTQwNGQxNWI1MjU2NmE1NzVlNTdkMjFjYjBiM2Y4MWQzYTJmZjM1N2FiZjhmNjRjY2YyYWQ0NDkiLCJpYXQiOjE2MDg0NzIwODQsIm5iZiI6MTYwODQ3MjA4NCwiZXhwIjoxNjQwMDA4MDg0LCJzdWIiOiIxIiwic2NvcGVzIjpbIioiXX0.nTbfzMg2thStTmX2dy1ZEB1JSILpwzLv5DMDVaxUY5NaC9GAj_VLAKNVJyOWvY5Ti-LFFvcQ8W8rVL4NesXnJJ89jLYwMoskCcvs8ZZNIJEfo6CAj5Lzp0Thc3eqHRDbOtVhgZojmdI5BsU9nBVAowOnVbLDv_3MoqP3MGFlSuhfVKgQZwLiVavvVjLVIZkxaEczmhCZIW1Dr_sYWkYzyDFRcZ2paz1lMzFBp7zLtYEsbCa6odSyMQxzxKZ-6h3WgpRjx34vrC6THH-zpf8TTlTM7ddmq1mHr_o3JvAHzfZCjqAFs3YU3uIeVI-U_-XXXZCHusy-QW7cCmJOBSzztiUKzUpNu-UdSHStPVeobUQTv86mNBMtgAZEXyflTTs7YkC6I83N9AAIW-tXyt50VcmHBKRy3qjzC-SwgOphuOLfSNIz0sy7PSckztWsx07XNKck_M-ajSthnS7FE9TDJ5Q5WC3UPBq056CYZckqOPByCJKf3ktmiOGKBXof05Peq-Uts0A0K6V16y0vr5m_v2Honxt3F0wfEWApyqHjEHopOu3zjTN7r3SOrjJMDQgmDduZBrk_iLrX4ggu6I5P70s2HVyT5mpvJiULWamanYaYgQfDSVFLeM4X6ffihrgzlle55rzRazfdNjspU_VusZWik4DOpMjZ-iHA9oo_lEA',
'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, json=payload)
print(response.text)
```
{% endtab %}
{% endtabs %}
## List the ucf projects
`GET` `https://api-v2.acrcloud.com/api/ucf-projects`
#### Query Parameters
| Name | Type | Description |
| ------ | ------ | ----------- |
| region | string | |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
```
{
"data": [
{
"id": 100000,
"uid": 1,
"name": "test",
"region": "eu-west-1",
"type": "BM",
"config": {
"days": 3,
"min_ms": 5000,
"max_ms": 300000
},
"created_at": "2020-12-28T04:57:13.000000Z",
"updated_at": "2020-12-28T04:57:13.000000Z"
}
],
"links": {
"first": "http://127.0.0.1:8080/api/ucf-projects?page=1",
"last": "http://127.0.0.1:8080/api/ucf-projects?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "http://127.0.0.1:8080/api/ucf-projects",
"per_page": 15,
"to": 1,
"total": 1
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="T" %}
```bash
curl --location --request GET 'http://127.0.0.1:8080/api/ucf-projects' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% endtabs %}
## Update a ucf project
`PUT` `https://api-v2.acrcloud.com/api/ucf-projects/:id`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------------ |
| id | number | the ucf project id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
#### Request Body
| Name | Type | Description |
| ------ | ------ | ----------- |
| config | object | |
| name | string | |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"uid": 1,
"name": "test",
"region": "eu-west-1",
"type": "BM",
"config": {
"days": 3,
"min_ms": 5000,
"max_ms": 300000
},
"updated_at": "2020-12-28T04:57:13.000000Z",
"created_at": "2020-12-28T04:57:13.000000Z",
"id": 100000
}
}
```
{% endtab %}
{% endtabs %}
## Delete a ucf project
`DELETE` `/api/ucf-projects/:id`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------------ |
| id | number | The ucf project id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
# BM Streams
## Import bm streams
`POST` `https://api-v2.acrcloud.com/api/ucf-projects/:pid/streams`
Import BM streams to project
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------- |
| pid | number | The project id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
#### Request Body
| Name | Type | Description |
| --------------- | ------ | ------------------------ |
| bm\_stream\_ids | array | The BM streams ids array |
| from | string | BM-CUSTOM or BM-DATABASE |
| bm\_project\_id | number | The BM project id |
{% tabs %}
{% tab title="200 Cake successfully retrieved." %}
```
{
"data": [
{
"uid": 1,
"pid": 10263,
"bm_stream_id": 191149,
"bm_project_id": 871,
"from": "BM-DATABASE",
"state": 1,
"updated_at": "2020-12-28T08:01:14.000000Z",
"created_at": "2020-12-28T08:01:14.000000Z",
"id": 79,
"bm_stream_name": "(ΛΑΜΨΗ) Lampsi 92.3 FM",
"bm_project_name": "test"
},
{
"uid": 1,
"pid": 10263,
"bm_stream_id": 198144,
"bm_project_id": 871,
"from": "BM-DATABASE",
"state": 1,
"updated_at": "2020-12-28T08:01:14.000000Z",
"created_at": "2020-12-28T08:01:14.000000Z",
"id": 80,
"bm_stream_name": ".977 Today's Hits",
"bm_project_name": "test"
}
]
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request POST 'https://api-v2.acrcloud.com/api/ucf-projects/10263/streams' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{"bm_stream_ids":["191149","198144"], "from":"BM-DATABASE", "bm_project_id":871}'
```
{% endtab %}
{% endtabs %}
## List the ucf streams
`GET` `https://api-v2.acrcloud.com/api/ucf-projects/:pid/streams`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------------ |
| pid | string | The ucf project id |
#### Query Parameters
| Name | Type | Description |
| --------- | ------ | ----------- |
| page | number | |
| per\_page | number | |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
```
{
"data": [
{
"id": 80,
"uid": 1,
"pid": 10263,
"bm_stream_id": "198144",
"bm_project_id": 871,
"from": "BM-DATABASE",
"state": 1,
"updated_at": "2020-12-28T08:01:14.000000Z",
"created_at": "2020-12-28T08:01:14.000000Z",
"bm_stream_name": ".977 Today's Hits",
"bm_project_name": "test"
},
{
"id": 79,
"uid": 1,
"pid": 10263,
"bm_stream_id": "191149",
"bm_project_id": 871,
"from": "BM-DATABASE",
"state": 1,
"updated_at": "2020-12-28T08:01:14.000000Z",
"created_at": "2020-12-28T08:01:14.000000Z",
"bm_stream_name": "(ΛΑΜΨΗ) Lampsi 92.3 FM",
"bm_project_name": "test"
}
],
"links": {
"first": "http://127.0.0.1:8080/api/ucf-projects/10263/streams?page=1",
"last": "http://127.0.0.1:8080/api/ucf-projects/10263/streams?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "http://127.0.0.1:8080/api/ucf-projects/10263/streams",
"per_page": 10,
"to": 2,
"total": 2
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/ucf-projects/10263/streams' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% endtabs %}
## Delete the bm streams
`DELETE` `https://api-v2.acrcloud.com/api/ucf-projects/:pid/streams/ids`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------------------------- |
| ids | string | The streams ids. Sparated by ',' |
| pid | number | The ucf project id |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="204 " %}
```
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request DELETE 'http://127.0.0.1:8080/api/ucf-projects/10263/streams/80' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% endtabs %}
# UCF Results
## List the ucf results
`GET` `https://api-v2.acrcloud.com/api/ucf-projects/:pid/results`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------------ |
| pid | number | The ucf project id |
#### Query Parameters
| Name | Type | Description |
| ------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| page | number | The page number |
| begin\_date | string | Filter the results by begin\_date. The format is "%Y-%m-%d" or "%Y-%m-%d %H:%M:%S" |
| end\_date | string | Filter the results by end\_date. The format is "%Y-%m-%d" or "%Y-%m-%d %H:%M:%S" |
| sortby | string | Sort the results by 'id', 'num', 'duration\_ms'. The default is sort by 'id'. |
| order | string | desc or asc. Default is desc. |
| status | string | 0:Pending results.
2: Edited results.
6: Reported results.
10: Bucketed results.
14: Reported & Bucketed results.
-1: Deleted results
-2: Deleted & Reserved results
|
| min | string | Filter the results by minimum duration. (seconds) |
| max | string | Filter the results by maximum duration.(seconds) |
| streams | string | Filter the results by streams ids. Separated by , |
| ucf\_id | string | Filter the results by ucf id. |
| label | string | 0: Unknown
1: Music
2: Speech
3: Music & Speech
4: Advertisement
|
| per\_page | boolean | The item number of one page |
| label\_value | string | if the label is advertisement, then the label\_value is the advertisement name |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 Cake successfully retrieved." %}
```
{
"data":[
{
"id":340335,
"acr_id":"d7a4ebc9685f23bdc843ed4146b35f69",
"status":0,
"label":2,
"num":3,
"duration_ms":131460,
"metadata":null,
"created_at":"2020-05-27 08:56:45",
"pid":10263,
"operators":[
{"operator":"ACRCloud","updated_at":"2022-04-27 08:09:49"},
{"operator":"ACRCloud","updated_at":"2022-04-27 08:10:27"}
],
"updated_at":"2020-05-27 08:56:45"
},
{
"id":340334,
"acr_id":"4fc390bfb9db91e904084715c530e25d",
"status":0,
"label":3,
"num":3,
"duration_ms":157840,
"metadata":null,
"created_at":"2020-05-27 08:56:41",
"pid":10263,
"operators":[],
"updated_at":"2020-05-27 08:56:45"
},
{
"id":340333,
"acr_id":"4965aefe6b33202f9a1fb000d2a00bd6",
"status":0,
"label":1,
"num":3,
"duration_ms":136740,
"metadata":null,
"created_at":"2020-05-27 08:49:18",
"pid":10263,
"operators":[],
"updated_at":"2020-05-27 08:56:45"
},
{
"id":340332,
"acr_id":"e0e99fd9dc89da03e5081b856dcbf609",
"status":0,
"label":2,
"num":2,
"duration_ms":130900,
"metadata":null,
"created_at":"2020-05-27 08:49:14",
"pid":10263,
"operators":[],
"updated_at":"2020-05-27 08:56:45"
},
{
"id":340331,
"acr_id":"79242e7fdf8db9063b75e5406adb2985",
"status":0,
"label":3,
"num":2,
"duration_ms":158820,
"metadata":null,
"created_at":"2020-05-27 08:49:10",
"pid":10263,
"operators":[],
"updated_at":"2020-05-27 08:56:45"
},
{
"id":340330,
"acr_id":"0ea18f0ef7548f99129086bb29699e87",
"status":0,
"label":3,
"num":4,
"duration_ms":120760,
"metadata":null,
"created_at":"2020-05-27 08:44:06",
"pid":10263,
"operators":[],
"updated_at":"2020-05-27 08:56:45"
},
{
"id":340328,
"acr_id":"f3e85570e94ae78735c49c4574422bf3",
"status":0,
"label":3,
"num":4,
"duration_ms":201060,
"metadata":null,
"created_at":"2020-05-27 08:43:57",
"pid":10263,
"operators":[],
"updated_at":"2020-05-27 08:56:45"
},
{
"id":340327,
"acr_id":"6fae20c216b2b212931d0b92ac505542",
"status":0,
"label":1,
"num":2,
"duration_ms":303900,
"metadata":null,
"created_at":"2020-05-27 08:43:50",
"pid":10263,
"operators":[],
"updated_at":"2020-05-27 08:56:45"
},
{
"id":340326,
"acr_id":"0eba7a977facffeed6b15e08d47cf135",
"status":0,
"label":2,
"num":2,
"duration_ms":194400,
"metadata":null,
"created_at":"2020-05-27 08:38:50",
"pid":10263,
"operators":[],
"updated_at":"2020-05-27 08:56:45"
},
{
"id":340325,
"acr_id":"c0f1b9e0a46f417db2634f55ebbc7954",
"status":0,
"label":1,
"num":2,
"duration_ms":129000,
"metadata":null,
"created_at":"2020-05-27 08:33:50",
"pid":10263,
"operators":[],
"updated_at":"2020-05-27 08:56:45"
}
],
"links":{
"first":"http://127.0.0.1:8080/api/ucf-projects/10263/results?per_page=10&status=0&page=1",
"last":"http://127.0.0.1:8080/api/ucf-projects/10263/results?per_page=10&status=0&page=9",
"prev":null,
"next":"http://127.0.0.1:8080/api/ucf-projects/10263/results?per_page=10&status=0&page=2"
},
"meta":{
"current_page":1,
"from":1,
"last_page":9,
"path":"http://127.0.0.1:8080/api/ucf-projects/10263/results",
"per_page":"10",
"to":10,
"total":90
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/ucf-projects/10263/results?page=1&per_page=10&status=0' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% endtabs %}
## List the details of one ucf item
`GET` `https://api-v2.acrcloud.com/api/ucf-projects/:pid/results/:ucf_id/details`
#### Path Parameters
| Name | Type | Description |
| ------- | ------ | -------------- |
| pid | number | The project id |
| ucf\_id | number | The ucf id |
#### Query Parameters
| Name | Type | Description |
| ----------- | ------ | ----------- |
| page | number | |
| per\_page | number | |
| begin\_date | string | |
| end\_date | string | |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
```
{
"data":[
{
"id":4708635,
"duration_ms":137520,
"acr_id":"d7a4ebc9685f23bdc843ed4146b35f69",
"begin_time":"2020-05-26 08:41:33",
"pid":10263,
"stream":{
"id":53,
"uid":1,
"pid":10263,
"bm_stream_id":"s-U3P7kHj",
"bm_project_id":10263,
"from":"BM-CUSTOM",
"state":2,
"updated_at":"2020-12-28T07:55:04.000000Z",
"created_at":"2020-05-28T03:53:03.000000Z",
"bm_stream_name":"RTM KL FM",
"bm_project_name":"PPM"
}
},
{
"id":4708634,
"duration_ms":132500,
"acr_id":"d7a4ebc9685f23bdc843ed4146b35f69",
"begin_time":"2020-05-25 08:43:03",
"pid":10263,
"stream":{
"id":53,
"uid":1,
"pid":10263,
"bm_stream_id":"s-U3P7kHj",
"bm_project_id":10263,
"from":"BM-CUSTOM",
"state":2,
"updated_at":"2020-12-28T07:55:04.000000Z",
"created_at":"2020-05-28T03:53:03.000000Z",
"bm_stream_name":"RTM KL FM",
"bm_project_name":"PPM"
}
},
{
"id":4708633,
"duration_ms":131460,
"acr_id":"d7a4ebc9685f23bdc843ed4146b35f69",
"begin_time":"2020-05-24 05:17:36",
"pid":10263,
"stream":{
"id":53,
"uid":1,
"pid":10263,
"bm_stream_id":"s-U3P7kHj",
"bm_project_id":10263,
"from":"BM-CUSTOM",
"state":2,
"updated_at":"2020-12-28T07:55:04.000000Z",
"created_at":"2020-05-28T03:53:03.000000Z",
"bm_stream_name":"RTM KL FM",
"bm_project_name":"PPM"
}
}
],
"links":{
"first":"http://127.0.0.1:8080/api/ucf-projects/10263/results/340335/details?per_page=10&page=1",
"last":"http://127.0.0.1:8080/api/ucf-projects/10263/results/340335/details?per_page=10&page=1",
"prev":null,
"next":null
},
"meta":{
"current_page":1,
"from":1,
"last_page":1,
"path":"http://127.0.0.1:8080/api/ucf-projects/10263/results/340335/details",
"per_page":"10",
"to":3,
"total":3
}
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request GET 'http://127.0.0.1:8080/api/ucf-projects/10263/results/340335/details?page=1&per_page=10' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% endtabs %}
## Get the ucf record url
`GET` `https://api-v2.acrcloud.com/api/ucf-projects/:pid/results/:ucf_id/record`
#### Path Parameters
| Name | Type | Description |
| ------- | ------ | ----------- |
| pid | string | |
| ucf\_id | string | |
#### Query Parameters
| Name | Type | Description |
| ------ | ------ | ---------------------------------------------------------------------------------------------------------- |
| extend | string | The extend length(seconds) at the beginning and ending. Default is 20 seconds. The max value is 60 seconds |
#### Headers
| Name | Type | Description |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |
{% tabs %}
{% tab title="200 " %}
```
{
"stream_id":"16323",
"begin":1590505455380,
"end":1590505576220,
"prefix_extend":20,
"suffix_extend":20,
"play_url":"https://api-v2.acrcloud.com/api/ucf-projects/10263/results/340337/play?stream_id=16323&begin=1590505455380&end=1590505576220&prefix=20&suffix=20"
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/ucf-projects/10263/results/340337/record' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% endtabs %}
## Delete a ucf item
`DELETE` `https://api-v2.acrcloud.com/api/ucf-projects/:pid/results/:ucf_id`
#### Path Parameters
| Name | Type | Description |
| ----------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pid\* | number | The ucf project id |
| ucf\_id\* | number | The ucf id |
| reserved | number | 0 or 1, if you set to 1, the item will got into the Ignore & Reserved queue that means If the same content is detected again in the future, it will still enter this queue and will not reappear in the pending list. |
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ------------ |
| Authorization\* | string | Bearer token |
{% tabs %}
{% tab title="204 " %}
```
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Curl" %}
```bash
curl --location --request DELETE 'https://api-v2.acrcloud.com/api/ucf-projects/results/4768035' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
```
{% endtab %}
{% endtabs %}
## make a ucf item status pending
`POST` `https://api-v2.acrcloud.com/api/ucf-projects/:pid/results/:ucf_id/pending`
#### Path Parameters
| Name | Type | Description |
| ----------------------------------------- | ------ | ------------------ |
| pid\* | Number | The ucf project id |
| ucf\_id\* | Number | The ucf id |
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ------------ |
| Authorization\* | String | Bearer token |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
"data": {
"id": 2794388,
"acr_id": "fb4e3147f7ed5b122266a754707b63ad",
"status": 0,
"label": 2,
"num": 2,
"duration_ms": 8300,
"metadata": null,
"operator": "",
"created_at": "2022-02-18 15:02:39",
"updated_at": "2022-02-21 04:37:48",
"pid": 1
}
}
```
{% endtab %}
{% endtabs %}
## Get one ucf item
`GET` `https://api-v2.acrcloud.com/api/ucf-projects/:pid/results/:ucf_id`
#### Path Parameters
| Name | Type | Description |
| ----------------------------------------- | ------------- | ------------------------ |
| pid\* | Number | The project id |
| ucf\_id\* | Number/String | The UCF item id or acrid |
{% tabs %}
{% tab title="200: OK " %}
````json
```json
{
"data": {
"id": 325483111,
"acr_id": "f111693a9ead2b2fda633543543f9d6a",
"status": 0,
"label": 4,
"label_value": "",
"num": 2,
"duration_ms": 21760,
"metadata": null,
"begin_time": "2023-05-17 11:17:10",
"fs_id": "668ad1b6-08cd-4313-b47e-79d9cc56e9aa",
"created_at": "2023-05-18 09:42:49",
"updated_at": "2023-05-22 07:56:33",
"pid": 12345,
"operators": [],
"speech": [
{
"id": 0,
"start": 0,
"end": 2.16,
"text": " Your U event is on at Dormezvous."
},
{
"id": 1,
"start": 2.16,
"end": 5.68,
"text": " For a limited time, get hot prices on your sleep essentials."
},
{
"id": 2,
"start": 5.68,
"end": 7.32,
"text": " Sleep well, stay well."
},
{
"id": 3,
"start": 7.32,
"end": 8.32,
"text": " Dormezvous."
},
{
"id": 4,
"start": 8.32,
"end": 10.84,
"text": " Are you thinking of a pool?"
},
{
"id": 5,
"start": 10.84,
"end": 12.44,
"text": " Above ground or in ground?"
},
{
"id": 6,
"start": 12.44,
"end": 13.68,
"text": " Trevi has good news for you."
},
{
"id": 7,
"start": 13.68,
"end": 15.48,
"text": " Book now and it'll be installed in June."
},
{
"id": 8,
"start": 15.48,
"end": 20.240000000000002,
"text": " And if you buy or rent a Trevi spa, it'll be delivered within 48 business hours."
},
{
"id": 9,
"start": 20.24,
"end": 36.879999999999995,
"text": " Starting Friday, take advantage of all Trevi's great weekend deals."
}
]
}
}
```
````
{% endtab %}
{% endtabs %}
# Metadata API
## Get music platforms metadata and links
`GET` `https://eu-api-v2.acrcloud.com/api/external-metadata/tracks`
You can get metadata and links from the platforms(Spotify, Apple Music, Youtube, Deezer, Tidal, Gaana, AWA, KKBOX, SoundCloud)
You can test on [this page](https://console.acrcloud.com/metadata-links?#/reference).
#### Query Parameters
| Name | Type | Description |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| source\_url | String | the platform's url, for example::
|
| isrc | String | ISRC |
| acr\_id | String | ACRCloud Music ID |
| platforms | String | The platform's metadata you want to get.
for example:
spotify,youtube
The default value is: spotify,deezer,youtube,applemusic
The number of platforms in the platforms parameter of a single request cannot exceed 5.
|
| query | String | Your search query, text format example: Eminem - Without Me
json format example( need to stringify the json data):
{"track":"Without Me", "artists":\["Eminem"]}
|
| include\_works | Number | 1 or 0, if you set it to 1, the response metadata will contain the contributors and works metadata if the tracks have |
| format | String | query string format, text or json. Default value is text |
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| Authorization\* | String | Bearer token. [How to create the token](https://docs.acrcloud.com/reference/console-api/accesstoken) |
{% tabs %}
{% tab title="200: OK " %}
```json
{
"data": [
{
"name": "Blank Space",
"disc_number": 1,
"track_number": 6,
"isrc": "USCJY1431309",
"genres": [
"Pop",
"Music"
],
"duration_ms": 230760,
"release_date": "2014-01-01",
"artists": [
{
"name": "Taylor Swift"
}
],
"album": {
"track_count": 20,
"upc": "00602577145735",
"release_date": "2018-10-26",
"label": "NOW20thAnniversary",
"cover": "https://is3-ssl.mzstatic.com/image/thumb/Music124/v4/0b/ae/32/0bae3256-7bb0-82f9-35f8-bca634c4aae8/18UMGIM62497.rgb.jpg/3000x3000bb.jpg",
"covers": {
"small": "https://is3-ssl.mzstatic.com/image/thumb/Music124/v4/0b/ae/32/0bae3256-7bb0-82f9-35f8-bca634c4aae8/18UMGIM62497.rgb.jpg/64x64bb.jpg",
"medium": "https://is3-ssl.mzstatic.com/image/thumb/Music124/v4/0b/ae/32/0bae3256-7bb0-82f9-35f8-bca634c4aae8/18UMGIM62497.rgb.jpg/300x300bb.jpg",
"large": "https://is3-ssl.mzstatic.com/image/thumb/Music124/v4/0b/ae/32/0bae3256-7bb0-82f9-35f8-bca634c4aae8/18UMGIM62497.rgb.jpg/3000x3000bb.jpg"
}
},
"external_metadata": {
"applemusic": [
{
"id": "1437689373",
"link": "https://music.apple.com/us/album/blank-space/1437689355?i=1437689373",
"preview": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview112/v4/b7/20/d4/b720d476-169f-d94e-1bed-7d91d43f2883/mzaf_12311605322954569753.plus.aac.p.m4a",
"artists": [
{
"id": "159260351"
}
],
"album": {
"id": "1437689355",
"cover": "https://is3-ssl.mzstatic.com/image/thumb/Music124/v4/0b/ae/32/0bae3256-7bb0-82f9-35f8-bca634c4aae8/18UMGIM62497.rgb.jpg/3000x3000bb.jpg"
}
},
{
"id": "1440933517",
"link": "https://music.apple.com/us/album/blank-space/1440933512?i=1440933517",
"preview": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview115/v4/81/bf/3d/81bf3ddc-75c0-46a3-d85b-9e79f0641a41/mzaf_2416740226777406648.plus.aac.p.m4a",
"artists": [
{
"id": "159260351"
}
],
"album": {
"id": "1440933512",
"cover": "https://is2-ssl.mzstatic.com/image/thumb/Music124/v4/54/45/87/544587c8-3f71-8484-3fdb-186a7d7b7326/00843930013609.rgb.jpg/2400x2400bb.jpg"
}
},
{
"id": "1445765740",
"link": "https://music.apple.com/us/album/blank-space/1445765736?i=1445765740",
"preview": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview115/v4/20/3b/f8/203bf8a6-4f53-8e6b-ec00-8afd01241ebe/mzaf_2559055475772421277.plus.aac.p.m4a",
"artists": [
{
"id": "159260351"
}
],
"album": {
"id": "1445765736",
"cover": "https://is5-ssl.mzstatic.com/image/thumb/Music124/v4/b2/38/d3/b238d354-1aec-f71b-8706-26fcb1738b6d/00843930039562.rgb.jpg/3000x3000bb.jpg"
}
}
],
"deezer": [
{
"id": "89077521",
"link": "https://www.deezer.com/track/89077521",
"artists": [
{
"id": 12246
}
],
"album": {
"id": 9007779,
"cover": "https://api.deezer.com/2.0/album/9007779/image"
}
}
],
"youtube": [
{
"id": "dC9QIUKviJU",
"link": "https://music.youtube.com/watch?v=dC9QIUKviJU",
"artists": [
{
"id": "UCPC0L1d253x-KuMNwa05TpA",
"link": "https://music.youtube.com/channel/UCPC0L1d253x-KuMNwa05TpA"
}
],
"album": {
"id": "MPREb_JiAQrbUtBdP",
"link": "https://music.youtube.com/browse/MPREb_JiAQrbUtBdP"
}
},
{
"id": "uakZpnmQGiE",
"link": "https://music.youtube.com/watch?v=uakZpnmQGiE",
"artists": [
{
"id": "UCPC0L1d253x-KuMNwa05TpA",
"link": "https://music.youtube.com/channel/UCPC0L1d253x-KuMNwa05TpA"
}
],
"album": {
"id": "MPREb_FqCrQJ3iwcD",
"link": "https://music.youtube.com/browse/MPREb_FqCrQJ3iwcD"
}
},
{
"id": "QIfZAPkF7_M",
"link": "https://music.youtube.com/watch?v=QIfZAPkF7_M",
"artists": [
{
"id": "UCbhKnJtOmuOuaoY5hGwtYgA",
"link": "https://music.youtube.com/channel/UCbhKnJtOmuOuaoY5hGwtYgA"
}
],
"album": {
"id": "MPREb_jucl3t8hdEz",
"link": "https://music.youtube.com/browse/MPREb_jucl3t8hdEz"
}
}
],
"spotify": [
{
"id": "1437689373",
"link": "https://music.apple.com/us/album/blank-space/1437689355?i=1437689373",
"preview": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview112/v4/b7/20/d4/b720d476-169f-d94e-1bed-7d91d43f2883/mzaf_12311605322954569753.plus.aac.p.m4a",
"artists": [
{
"id": "159260351"
}
],
"album": {
"id": "1437689355",
"cover": "https://is3-ssl.mzstatic.com/image/thumb/Music124/v4/0b/ae/32/0bae3256-7bb0-82f9-35f8-bca634c4aae8/18UMGIM62497.rgb.jpg/3000x3000bb.jpg"
}
}
]
},
"type": "track",
"works": [
{
"iswc": "T9155554271",
"contributors": [
{
"name": "MAX MARTIN",
"ipi": 254380962,
"roles": [
"Composer"
]
},
{
"name": "SHELLBACK ",
"ipi": 583608328,
"roles": [
"Composer"
]
},
{
"name": "SWIFT TAYLOR ALISON",
"ipi": 454808047,
"roles": [
"Composer"
]
},
{
"name": "SONY/ATV TREE PUBLISHING ",
"ipi": 425389934,
"roles": [
"Publisher"
]
},
{
"name": "TAYLOR SWIFT MUSIC ",
"ipi": 497322918,
"roles": [
"Publisher"
]
}
],
"name": "BLANK SPACE VOICE MEMO"
},
{
"iswc": "T9156975165",
"contributors": [
{
"name": "MAX MARTIN",
"ipi": 254380962,
"roles": [
"Composer"
]
},
{
"name": "SHELLBACK ",
"ipi": 583608328,
"roles": [
"Composer"
]
},
{
"name": "SWIFT TAYLOR ALISON",
"ipi": 454808047,
"roles": [
"Composer"
]
},
{
"name": "MXM MUSIC AB ",
"ipi": 657349509,
"roles": [
"Publisher"
]
},
{
"name": "SONY/ATV TREE PUBLISHING ",
"ipi": 425389934,
"roles": [
"Publisher"
]
},
{
"name": "KMR MUSIC ROYALTIES II SCSP ",
"ipi": 858735976,
"roles": [
"Publisher"
]
},
{
"name": "TAYLOR SWIFT MUSIC ",
"ipi": 497322918,
"roles": [
"Publisher"
]
}
],
"name": "BLANK SPACE VOICE MEMO"
},
{
"iswc": "T9236690770",
"contributors": [
{
"name": "MAX MARTIN",
"ipi": 254380962,
"roles": [
"Composer"
]
},
{
"name": "SCHUSTER JOHAN KARL",
"ipi": 444712759,
"roles": [
"Composer"
]
},
{
"name": "SWIFT TAYLOR ALISON",
"ipi": 454808047,
"roles": [
"Composer"
]
},
{
"name": "PAYAMI ALI",
"ipi": 473985994,
"roles": [
"Composer"
]
}
],
"name": "BLANK SPACE/STYLE"
}
]
}
]
}
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Python" %}
```python
import requests
url = "https://eu-api-v2.acrcloud.com/api/external-metadata/tracks"
payload={}
headers = {
'Authorization': 'Bearer your token'
}
params = {
'query':json.dumps({"track": "jus sayin", "artists": ["steve lawler","Dateless"]}),
'format':'json'
}
response = requests.get(url, headers=headers, params=params)
print(response.text)
```
{% endtab %}
{% tab title="NodeJs - Axios" %}
```javascript
const axios = require('axios');
let config = {
method: 'get',
maxBodyLength: Infinity,
url: 'https://eu-api-v2.acrcloud.com/api/external-metadata/tracks',
params: {
query:JSON.stringify({"track": "jus sayin", "artists": ["steve lawler", "Dateless"]}),
format:'json'
},
headers: {
'Authorization': 'Bearer YOUR_TOKEN'
}
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
```
{% endtab %}
{% endtabs %}
# Audio File Fingerprinting Tool
## Downloads
{% embed url="" %}
## Usage
```
Usage: ./acr_extr [options] [-i infile]
For Example:
# ./acr_extr -i inputfile
# ./acr_extr -i inputfile -o outputfile
Getting help:
-h -- print basic options
-v -- print vertion
Options:
-i input file.
-o Output file. If do not have this option, dir of output file is the same with input file.
-au If you add this option, it will save the audio data as decoded from input file(formatter: RIFF (little-endian) data, WAVE audio, Microsoft PCM, 16 bit, mono 8000 Hz).
example: ./acrcloud_extr -au -i inputfile
--debug If you add this option, it will print all infomation.
```
# Local Monitoring Tool
### Overview
This tool is used for [ACRCloud Local Broadcast Monitoring Service](https://console.acrcloud.com/bm#/dashboard)
Local Broadcast Monitoring System([GitHub](https://github.com/acrcloud/acrcloud_local_monitor)) is used to monitor live radio streams on your own local server.
### Requirements
* Python 2.7
* Works on Linux/Windows
* Follow one of the tutorials to create a project and get your host, access\_key.
* [Broadcast Monitoring for Music](/get-started/tutorials/broadcast-monitoring-for-music)
* [Broadcast Monitoring for Custom Content](/get-started/tutorials/broadcast-monitoring-for-custom-content)
### How To Use
1. You should register an account on the [ACRCloud platform](https://console.acrcloud.com/), and create a [Broadcast Monitoring project](/get-started/tutorials/broadcast-monitoring-for-music) with local monitoring type, you will get access\_key, then add your live radio streams in your project.
2. Clone the code in your local server.
3. Install MySQL, import acrcloud\_database.sql to your mysql server. `$mysql -uroot -p < acrcloud_database.sql`.
4. Modify configuration file (acrcloud\_config.py), fill access\_key, access\_secret and database info in the config file.
5. Run `python acrcloud_local_server.py` to start monitor server.
6. You can use client to refresh, get stream state, pause and restart stream, run `python acrcloud_client.py`.
7. You can use `Ctrl + \` to stop monitor server (in Linux).
8. You can get monitoring results in your MySql database.
9. If you want to record recognize audio, you can set config\["record"]\["record"]=3 (default is 0 and it means not record).
You can set config\["record"]\["record\_dir"] to specify the save path.
You can set config\["record"]\["record\_save\_days"] to specify the keep days of record files.
These config can be set in "acrcloud\_config.py"
### Python Dependency Library
1. [Twisted](https://github.com/twisted/twisted)
2. [requests](https://pypi.org/project/requests/)
3. [fuzzywuzzy](https://github.com/seatgeek/fuzzywuzzy)
4. [beautifulsoup4](https://pypi.python.org/pypi/beautifulsoup4)
5. [MySQL-Python](https://pypi.python.org/pypi/MySQL-python)
### Install on Windows
1. Install Windows Runtime Library
* X86: [download and install Library(vcredist\_x86.exe)](https://www.microsoft.com/en-us/download/details.aspx?id=5555)
* x64: [download and install Library(vcredist\_x64.exe)](https://www.microsoft.com/en-us/download/details.aspx?id=14632)
2. Install [Mysql](https://dev.mysql.com/downloads/installer/) on your windows
3. Create Databases(in acrcloud\_local\_monitor direction and run this command)
`mysql -uroot -p < acrcloud_database.sql`
4. Install [Python](https://www.python.org/downloads/)
5. Install Python Dependency Library(in acrcloud\_local\_monitor direction and run the script)
`.\install_python_packages_for_windows.bat`
6. Install [MySQL-python](https://pypi.org/project/MySQL-python/1.2.5/)
* Open [https://www.lfd.uci.edu/\~gohlke/pythonlibs/](https://www.lfd.uci.edu/~gohlke/pythonlibs/#mysql-python)
* Find and Download:
`MySQL_python‑1.2.5‑cp27‑none‑win32.whl (or MySQL_python‑1.2.5‑cp27‑none‑win_amd64.whl)`
* `python -m pip install MySQL_python‑1.2.5‑cp27‑none‑win32.whl`
* `python -m pip install mysql-python`
7. Copy the ACRCloud Library into the acrcloud\_local\_monitor direction according to your system.
* X86: copy from winlibs/win32/acrcloud\_stream\_decode.pyd to acrcloud\_local\_monitor direction
* X64: copy from winlibs/win64/acrcloud\_stream\_decode.pyd to acrcloud\_local\_monitor direction
8. If you have created Local Project and add some streams, config the acrcloud\_config.py with your access\_key, and mysql information, then start the local server
`python acrcloud_local_server.py`
9. Stop the local monitor server
`python acrcloud_stop.py` and Ctrl-C
### Run as a Docker Container
1. Install Docker
* If you are using Windows: Download [Docker Desktop for Windows](https://download.docker.com/win/stable/Docker%20for%20Windows%20Installer.exe) and install.
* If you are using MacOs: Download [Docker Desktop for Mac](https://download.docker.com/mac/stable/Docker.dmg) and install.
* If you are using Linux: Open the Terminal and input bash <(curl -s )
2. Run following command
* `git clone https://github.com/acrcloud/acrcloud_local_monitor`
* `cd acrcloud_local_monitor`
* Change the config file "acrcloud\_config.py", fill in your project "access\_key", and mysql setting(host, port, user, passwd), **if Mysql was installed in your computer, please create a remote user and set field "host" to your private IP(ifconfig in Linux or ipconfig in Windows, "host.docker.internal" in Mac OS)**
* `docker build -t acrcloud/acr_local_monitor_image:v1 .`
* `docker run --rm -itv //acrcloud_local_monitor:/docker_local_monitor --name="acr_local_monitor" acrcloud/acr_local_monitor_image:v1`
# Live Channel Fingerprinting Tool
## Introduction
* The Live Channel Fingerprinting Tool ([Download](https://github.com/acrcloud/live_stream_client)) is used for extracting and uploading features from live TV channel streams in real-time.
* After the app is integrated, our SDK can detect your channels by recording the audio for just a few seconds in real-time.
* We assume that this tool will be running on your server, which already has quick network access to the streams so that our system guarantees the Real-Time performance to detect the live channels.
## Preparations
* Before using this tool, you must register on our platform and log into your dashboard.
* Sign up now for a free 14 day trial:
* Create a “Live Channel” bucket and add the url of your streams into it.
* [**Create a console access key pairs on account page**](https://console.acrcloud.com/account/keys#/old-accesskeys) and input this key pairs to your client.conf file
* Input your Live Bucket Name to the client.conf file.
* Run the stream.py
* Create a “Live Channel Detection” project and attach the bucket which contains your chosen stream urls.
* Then you can use our SDK to detect the current stream.
## **Install**
How to run:
1\) Download the tool.
`git clone https://github.com/acrcloud/live_stream_client live_stream_client`
2\) Enter the operating system you use.
`cd Linux/x86-64`
3\) Edit the client.conf file and replace the console key pairs ( access\_key, access\_secret ), bucket\_name with your own.
`python stream.py client.conf`
or
`nohup python stream.py client.conf &`
How to update/add stream URL:
1\) Update/add stream URL to the Live Channel Bucket on the [Console](https://console.acrcloud.com/)
2\) Kill stream.py process in your server.
`ps -ef | grep stream.py | grep -v grep | awk '{print $2}'| xargs kill -9`
3\) Restart the stream.py
`python stream.py client.conf`
or
`nohup python stream.py client.conf &`
## How to use the timeshifted feature?
1. Create a LiveTimeshift bucket, set the bucket type “LiveTimeshift”.
2. Enable the timeshift feature for the live channels in the Live bucket
3. Import the live channels to the LiveTimeshift bucket
## How to check the live fingerprinting status?
1. Login to your account from [Console](http://console.acrcloud.com/)
2. Make sure you are in the region where you send the live fingerprinting
3. Click “Live channel” under the bucket
4. Click in the bucket you build for the channels and see each status of the channel
**Processing: The real-time fingerprint of the stream has not yet reached the platform.**
**Ready: The fingerprint of the live stream is ready for detection**
# File Scan Tool
## Download
{% embed url="" %}
# Definition of Terms
## 3rd Party ID Integration
We integrate popular 3rd party music related services to display their ID’s in our recognition results, this means our clients can easily link our recognition results with other services.
Supported 3rd party IDs:
* ISRC
* UPC
* [Spotify](https://www.spotify.com/)
* [Deezer](http://www.deezer.com/)
* [YouTube](https://www.youtube.com/)
* [MusicBrainz](https://musicbrainz.org/)
## Brand Exposure
If you choose the plan with “Brand Exposure Required” then please follow the rules to expose our brand appropriately within your project. Place the text, logo and link where you use or display the recognition results.
For more information of how to expose the brand please refer to [Branding & Attribution Guidelines](https://www.acrcloud.com/branding).
## Broadcast Monitoring Status
| Status | Description |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Running | The stream is working |
| Timeout | The stream is currently not stable, no results will be shown at the moment, the system will try to rectify the stream, and in the meantime why not use another stream link. |
| Invalid URL | The stream URL has a problem, our system can not access the stream, please check the stream or change to another stream URL. |
| Paused | The stream was paused temporarily, you may need to restart the stream. |
## Valid Request
Valid Requests = Requests with results + Requests with no results/2
## Monitoring Type
Monitor streams on ACRCloud: The streams will be captured on ACRCloud, you will need to collect the internet stream URLs and input them on ACRCloud system.
Monitor streams on your local server: The streams will be captured on your own server, this option requires you to prepare your own server to capture streams but the recognition part will be done on ACRCloud system.
## Terminology
To clarify our terminology in EDM and mixes:
**Speed Scaling**: If both scales of time and speed are changed proportionally, we call this a change in “speed”: the song is played faster and at the same time at a higher pitch. This can be achieved by simply changing the rotational speed of the turntable, or by modifying the sampling rate of a digital media player – while keeping the sampling rate of the audio encoding unchanged.
**Tempo Shifting/Time Scaling**: Changing the time scale only will be referred to as a “tempo” change: here, the audio is sped up or slowed down without observable changes in pitch.
**Pitch Shifting/Frequency Scaling**: If only the frequency scale is modified but time is not scaled, this will be called pitch shifting.
# Service Usage
## Difference Between Custom Files and Live Channel Bucket
#### **Custom Files Bucket**
Manage fingerprints of digital content which are in file format. The developer can upload the audio / video file of the content to ACRCloud bucket as the identification sample. For example advertisement audios.
Files can be uploaded to the bucket so it can be used as fingerprint samples for content monitoring and second screen triggering.
#### **Live Channel Bucket**
Manage real time fingerprints of the digitized **streaming** content like the broadcast of TV or radio channels. Live stream is from an encoder and in a format of url under common protocols (udp, http, rtsp,mms) such as ( udp\://192.168.1.2 or [http://192.168.1.1](http://192.168.1.1/))
## Difference Between Live Channel Detection and Broadcast Monitoring projects
#### Live Channel Detection
This kind of project is for making second screen apps, which **recognize** the **live channel signal itself** to know which channel the audiences are watching.
You need to manage **Live Channel Buckets** and deploy the [Live Channel Fingerprinting Tool](https://www.acrcloud.com/docs/fingerprinting-tools/live-channel-fingerprinting-tool/) on your local server to ingest real time fingerprints of live channels into your Live Channel bucket then the mobile SDK can detect the live channel ID.
#### Broadcast Monitoring
Broadcast Monitoring project is used to **recognize** **music** or **custom** **content** such as commercials played on broadcast ( radio or tv ).
You need to manage **Custom Files Buckets** to upload your own files you want to monitor.
## How to Check Usage Statistics?
The statistics can be found by the project under detail section of the project you built.
## How to Choose Client-End Audio Source?
### **Explanation**
#### Recorded Audio
This source of audio always introduces noise with the content you want to recognize.
Typically the **audio captured via microphone** and the **recording files with noise** should be using this type of source.
#### Line-in Audio
This source of audio should be the **original files or the audio without noise**.
{% hint style="info" %}
*Recorded Audio is more sensitive than Line-in Audio in recognition, but that doesn’t mean you can always use Recorded Audio in all of scenarios, it would be more false positions if you use Recording Audio in the scenarios should be using Line-in Audio.*
{% endhint %}
### **Scenario**
#### Recorded Audio
* You want to make a Shazam alike app to recognize music or TV from the audio captured via microphone.
* You want to recognize background music over the TV drama, movies or TV shows.
* Although in this scenario you want to recognize something in the recording files, but background music in this kind of content always with people talks and other kind of noise alone with the music.
#### Line-in Audio
* You want to recognize original files of music to get metadata.
* You want to recognize music or commercials from recording files of radio live streams.
## What is a valid Stream URL?
1. Make sure the stream URL can be played by player like VLC.
2. Make sure the stream can be played on the server which you install the fingerprint extract tools.
3. (Optional) If you do live channel detection on TV broadcast, make sure the stream play status is not slower than what is showing on the audience’s TV.
## Why there is “record error” from the SDK?
{“status”:{“code”:2000,”msg”:”record error”,”version”:”1.0″}}
It happens to appear with Android phones when the app has no authorization for recording. Please authorize the recording for the app from settings. In some circumstance, the tool category app will kill the recording authorization from other apps.
P.s. Android emulator does not support recording function, so it can’t work. Please use an android phone instead.
## Define metadata templates for custom buckets
You can add multiple custom metadata fields to the buckets by adding a metadata template to the bucket, it will let you add custom metadata fields efficiently.
You can add multiple metadata fields and separate them with commas:
You will find the metadata fields you added in the User-defined Fields as below:
## Live Channel Bucket Types
There are 2 types of Live Channel buckets:
* Ingest from local server: You will need to setup the local server for ingesting the live channels;
* Import from existing channels: If you already have the existing live channels in your buckets or you want to use the public live channels shared by others, you can select this type of bucket and import the existing channels. You don’t need to have the local server to ingest the live channels;
# AI Music Detection
This FAQ explains how ACRCloud's AI Music Detection feature works for audio content, including prediction thresholds, output interpretation, supported source categories, and performance notes.
***
### What does AI Music Detection do?
ACRCloud's AI Music Detection feature helps customers assess whether submitted audio content is more likely to be AI-generated or human-created.
It is designed to support content inspection and risk assessment workflows. Detection results should be interpreted as model outputs based on statistical patterns in the audio, rather than as definitive proof of origin.
***
### How does AI Music Detection work?
ACRCloud uses advanced, state-of-the-art detection technology to train specialized models for identifying whether audio content is AI-generated or human-created.
For each inspected audio file, the system returns:
* a binary prediction result
* an `ai_probability` score
* `source_probabilities` for supported source categories
Both `ai_probability` and `source_probabilities` are generated directly by the model and are not manually adjusted or post-processed by human operators.
***
### What threshold determines `ai_generated` vs. `human`?
The current threshold is **50%**.
* If `ai_probability >= 50%`, the output is `ai_generated`
* If `ai_probability < 50%`, the output is `human`
***
### Is AI Detection generally available?
Yes. AI Detection is **generally available** and has been officially released.
***
### What performance data is available?
The following figures are based on ACRCloud's internal evaluation dataset for the current model version.
#### Binary Confusion Matrix (Human vs. AI)
* **Precision (AI): 99.98%**
* **Recall (AI): 99.94%**
* **False Positive Rate: 0.06% of Human**
* **False Negative Rate: 0.06% of AI**
#### Per-Source Accuracy
* **human**: 99.91%
* **suno**: 99.86%
* **udio**: 99.93%
* **sonauto**: 98.81%
* **mureka**: 99.99%
* **rdiffusion**: 98.00%
> These results reflect performance on internal test data and are provided for reference only. Actual performance may vary depending on audio quality, transformations, compression, mixing, editing, and real-world usage conditions.
***
### What source categories are currently supported?
The currently supported source categories exposed in the platform include:
* `human`
* `suno`
* `udio`
* `sonauto`
* `mureka`
* `rdiffusion`
We are actively expanding supported source coverage and are working to include additional model sources such as **ElevenLabs**, **MiniMax**, and **Seed-Music**.
Supported source coverage may continue to evolve over time as generative audio models and market usage change.
***
### How should `ai_probability` and `source_probabilities` be interpreted?
We recommend that customers interpret the output as follows:
* Use the **binary prediction** for straightforward workflow decisions
* Use **`ai_probability`** as a confidence reference
* Use **`source_probabilities`** as supporting signals for source attribution analysis
* Consider the result together with other contextual or operational signals where appropriate
Both `ai_probability` and `source_probabilities` are direct outputs from the model itself.
Detection results should not be treated as the sole basis for legal, enforcement, or other high-impact decisions without additional review.
***
### Notes
* Detection results are probabilistic model outputs, not definitive proof of origin.
* Performance may vary across different content types and real-world conditions.
* Supported source categories may be updated over time as the model evolves.
* Third-party model or product names are used only to describe detection coverage and do not imply partnership, endorsement, or affiliation.
***
### Suggested Disclaimer
The AI Detection feature provides probabilistic model outputs based on patterns identified in submitted audio content. Results are intended to assist review and inspection workflows and should not be interpreted as definitive proof of content origin. Performance metrics shown in this document are based on internal evaluation data and may vary in real-world use cases.