Songs uploading

If you want to recognize music among the songs you've uploaded, this is the endpoint you use for uploading your songs.

Access to uploading

To get access to the endpoint, contact the AudD representative that you work with. Access to this endpoint isn't available by default.

Uploading music to our main DB

This is not the information for our partners. To upload your catalog to our main DB and to update it, ask the AudD representative you work with to give you a link to the correct page.

The songs uploaded via this endpoint will be available for recognition only to you.

Necessary rights

By uploading any audio files, you confirm that you have the rights to do so and to give us the rights to process these files, to store the files for up to 72 hours, to make digital "fingerprints" from the files and to store and process those fingerprints for an unrestricted period of time.

Adding additional metadata

We strongly recommend to store any metadata on your side and send us integer IDs linked to the metadata. Contact us if you want to store on our side and get with the recognition results not just the IDs, but also the additional metadata.

How to send files

There are two ways of sending files to the API:

• Provide a URL of the file. Our server will download and recognize the file. Send the URL in the url parameter.
• Post the file using multipart/form-data in the usual way the files are uploaded via the browser. Send the file in the file parameter, by POST. Useful if the file is not available by a URL.

You can try to send a file from a browser here.

post

Upload a song

https://api.audd.io/upload/

Request

Form Data Parameters

api_token

REQUIRED

string

Your api_token

url

POSSIBLY REQUIRED

string

The URL of the song

file

POSSIBLY REQUIRED

binary

The file of the song

audio_id

REQUIRED

integer

ID of the song. You will get the ID you set with the recognition results

Response

The song was successfully uploaded.

200: OK

{
  "status": "success",
  "result": null
}

Code examples

Send a file URL

Python

Plain HTTP, no SDK:

curl https://api.audd.io/upload/ \
    -F api_token='your api_token' \
    -F url='https://music.audd.io/ED.wav' \
    -F audio_id='51885'

Node

With the SDK:

pip install audd

audd.custom_catalog.add(audio_id=42, source="https://my.song.mp3")

Full Python reference →

Or send the request yourself, without the SDK:

import requests
data = {
    'api_token': 'your api_token',
    'url': 'https://music.audd.io/ED.wav',
    'audio_id': '51885',
}
result = requests.post('https://api.audd.io/upload/', data=data)
print(result.text)

Go

With the SDK:

npm install @audd/sdk

await audd.customCatalog.add({ audioId: 42, source: "https://my.song.mp3" });

Full Node reference →

Or send the request yourself, without the SDK:

var axios = require("axios");

var data = {
    'api_token': 'your api_token',
    'url': 'https://music.audd.io/ED.wav',
    'audio_id': '51885',
};

axios({
    method: 'post',
    url: 'https://api.audd.io/upload/',
    data: data,
    headers: { 'Content-Type': 'multipart/form-data' },
})
.then((response) => {
    console.log(response);
})
.catch((error) =>  {
    console.log(error);
});

Rust

With the SDK:

go get github.com/AudDMusic/audd-go

package main

import (
    "log"

    audd "github.com/AudDMusic/audd-go"
)

func main() {
    client := audd.NewClient("your api_token")
    defer client.Close()

    if err := client.CustomCatalog().Add(51885, "https://music.audd.io/ED.wav"); err != nil {
        log.Fatal(err)
    }
}

Full Go SDK reference →

PHP

With the SDK:

cargo add audd

client.custom_catalog().add(42, "https://my.song.mp3").await?;

Full Rust reference →

Swift

With the SDK:

composer require audd/audd

$audd->customCatalog->add(audioId: 42, source: 'https://my.song.mp3');

Full PHP reference →

Or send the request yourself, without the SDK:

<?php
$data = [
    'api_token' => 'your api_token',
    'url' => 'https://music.audd.io/ED.wav',
    'audio_id' => '51885',
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_URL, 'https://api.audd.io/upload/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
$result = curl_exec($ch);
curl_close($ch);
echo $result;

Kotlin

With the SDK:

// Package.swift, in dependencies:
.package(url: "https://github.com/AudDMusic/audd-swift", from: "1.5.19"),

try await audd.customCatalog.add(audioID: 42, source: "https://my.song.mp3")

Full Swift reference →

C#

With the SDK:

// build.gradle.kts
implementation("io.audd:audd-kotlin:1.5.16")

audd.customCatalog.add(audioId = 42, source = Source.Url("https://my.song.mp3"))

Full Kotlin reference →

Java

With the SDK:

dotnet add package AudD

await audd.CustomCatalog.AddAsync(42, "https://my.song.mp3");

Full C# reference →

C

With the SDK:

<!-- pom.xml -->
<dependency>
  <groupId>io.audd</groupId>
  <artifactId>audd</artifactId>
  <version>1.5.16</version>
</dependency>

audd.customCatalog().add(42, "https://my.song.mp3");

Full Java reference →

Or send the request yourself, without the SDK:

// requires OkHttp
OkHttpClient client = new OkHttpClient();
RequestBody data = new MultipartBody.Builder().setType(MultipartBody.FORM)
    .addFormDataPart("api_token", "your api_token")
    .addFormDataPart("url", "https://music.audd.io/ED.wav")
    .addFormDataPart("audio_id", "51885").build();
Request request = new Request.Builder().url("https://api.audd.io/upload/")
    .post(data).build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());

C++

With the SDK:

# CMakeLists.txt
FetchContent_Declare(audd
    GIT_REPOSITORY https://github.com/AudDMusic/audd-c.git
    GIT_TAG        v1.5.16)
FetchContent_MakeAvailable(audd)
target_link_libraries(your_app PRIVATE audd)

audd_custom_catalog_add(client, 42, audd_source_url("https://my.song.mp3"));

Full C reference →

curl

With the SDK:

# CMakeLists.txt (after installing audd-cpp)
find_package(audd CONFIG REQUIRED)
target_link_libraries(your_app PRIVATE audd::audd)

client.custom_catalog().add(42, audd::Source::url("https://my.song.mp3"));

Full C++ reference →

Send a local file

Python

Plain HTTP, no SDK:

curl https://api.audd.io/upload/ \
    -F api_token='your api_token' \ 
    -F file=@/path/to/song.wav \
    -F audio_id='51885'

Node

With the SDK:

pip install audd

audd.custom_catalog.add(audio_id=42, source="https://my.song.mp3")

Full Python reference →

Or send the request yourself, without the SDK:

import requests
data = {
    'api_token': 'your api_token',
    'audio_id': '51885',
}
files = {
    'file': open('/path/to/song.wav', 'rb'),
}
result = requests.post('https://api.audd.io/upload/', data=data, files=files)
print(result.text)

Go

With the SDK:

npm install @audd/sdk

await audd.customCatalog.add({ audioId: 42, source: "https://my.song.mp3" });

Full Node reference →

Or send the request yourself, without the SDK:

var axios = require("axios");
var fs = require('fs');

var data = {
    'api_token': 'your api_token',
    'file': fs.createReadStream('/path/to/song.wav'),
    'audio_id': '51885',
};

axios({
    method: 'post',
    url: 'https://api.audd.io/upload/',
    data: data,
    headers: { 'Content-Type': 'multipart/form-data' },
})
.then((response) => {
    console.log(response);
})
.catch((error) =>  {
    console.log(error);
});

Rust

With the SDK:

go get github.com/AudDMusic/audd-go

package main

import (
    "log"
    "os"

    audd "github.com/AudDMusic/audd-go"
)

func main() {
    client := audd.NewClient("your api_token")
    defer client.Close()

    f, err := os.Open("/path/to/song.wav")
    if err != nil {
        log.Fatal(err)
    }
    defer f.Close()

    if err := client.CustomCatalog().Add(51885, f); err != nil {
        log.Fatal(err)
    }
}

Full Go SDK reference →

PHP

With the SDK:

cargo add audd

client.custom_catalog().add(42, "https://my.song.mp3").await?;

Full Rust reference →

Swift

With the SDK:

composer require audd/audd

$audd->customCatalog->add(audioId: 42, source: 'https://my.song.mp3');

Full PHP reference →

Or send the request yourself, without the SDK:

<?php
$data = [
    'api_token' => 'your api_token',
    'file' => curl_file_create('/path/to/song.wav', 
        'application/octet-stream', 'file'),
    'audio_id' => '51885',
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_URL, 'https://api.audd.io/upload/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
$result = curl_exec($ch);
curl_close($ch);
echo $result;

Kotlin

With the SDK:

// Package.swift, in dependencies:
.package(url: "https://github.com/AudDMusic/audd-swift", from: "1.5.19"),

try await audd.customCatalog.add(audioID: 42, source: "https://my.song.mp3")

Full Swift reference →

C#

With the SDK:

// build.gradle.kts
implementation("io.audd:audd-kotlin:1.5.16")

audd.customCatalog.add(audioId = 42, source = Source.Url("https://my.song.mp3"))

Full Kotlin reference →

Java

With the SDK:

dotnet add package AudD

await audd.CustomCatalog.AddAsync(42, "https://my.song.mp3");

Full C# reference →

C

With the SDK:

<!-- pom.xml -->
<dependency>
  <groupId>io.audd</groupId>
  <artifactId>audd</artifactId>
  <version>1.5.16</version>
</dependency>

audd.customCatalog().add(42, "https://my.song.mp3");

Full Java reference →

Or send the request yourself, without the SDK:

// requires OkHttp
final MediaType MEDIA_TYPE_MP3 = MediaType.get("audio/mpeg; charset=utf-8");
File file = new File("/path/to/song.wav");
OkHttpClient client = new OkHttpClient();
RequestBody data = new MultipartBody.Builder().setType(MultipartBody.FORM)
    .addFormDataPart("api_token", "your api_token")
    .addFormDataPart("file", file.getName(), 
        RequestBody.Companion.create(file, MEDIA_TYPE_MP3))
    .addFormDataPart("audio_id", "51885").build();
Request request = new Request.Builder().url("https://api.audd.io/upload/")
    .post(data).build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());

C++

With the SDK:

# CMakeLists.txt
FetchContent_Declare(audd
    GIT_REPOSITORY https://github.com/AudDMusic/audd-c.git
    GIT_TAG        v1.5.16)
FetchContent_MakeAvailable(audd)
target_link_libraries(your_app PRIVATE audd)

audd_custom_catalog_add(client, 42, audd_source_url("https://my.song.mp3"));

Full C reference →

curl

With the SDK:

# CMakeLists.txt (after installing audd-cpp)
find_package(audd CONFIG REQUIRED)
target_link_libraries(your_app PRIVATE audd::audd)

client.custom_catalog().add(42, audd::Source::url("https://my.song.mp3"));

Full C++ reference →