### Install audd-go SDK

Source: https://docs.audd.io/sdks/go.md

Install the audd-go SDK using the go get command.

```sh
go get github.com/AudDMusic/audd-go
```

--------------------------------

### Install and Use Go SDK

Source: https://docs.audd.io/sdks

Get the Go SDK and use it to recognize a song from a URL. Replace 'your-api-token' with your actual API token.

```sh
go get github.com/AudDMusic/audd-go
```

```go
client := audd.NewClient("your-api-token")
defer client.Close()

result, _ := client.Recognize("https://audd.tech/example.mp3", nil)
fmt.Printf("%s — %s\n", result.Artist, result.Title)
```

--------------------------------

### Install and Use PHP SDK

Source: https://docs.audd.io/sdks

Install the PHP SDK using Composer and use it to recognize a song from a URL. Replace 'your-api-token' with your actual API token.

```bash
composer require audd/audd
```

```php
use AudD\AudD;

$audd = new AudD('your-api-token');
$r = $audd->recognize('https://audd.tech/example.mp3');
echo $r->artist . ' — ' . $r->title;
```

--------------------------------

### Install Node.js SDK

Source: https://docs.audd.io/sdks/node

Install the Node.js SDK using npm. Yarn and pnpm can also be used.

```bash
npm install @audd/sdk
```

--------------------------------

### Install audd-python SDK

Source: https://docs.audd.io/sdks/python

Install the audd-python SDK using pip. This is the first step to using the library.

```bash
pip install audd
```

--------------------------------

### Install and Use Python SDK

Source: https://docs.audd.io/sdks

Install the Python SDK using pip and use it to recognize a song from a URL. Replace 'your-api-token' with your actual API token.

```bash
pip install audd
```

```python
from audd import AudD

audd = AudD("your-api-token")
result = audd.recognize("https://audd.tech/example.mp3")
print(f"{result.artist} — {result.title}")
```

--------------------------------

### Install and Use Node.js SDK

Source: https://docs.audd.io/sdks

Install the Node.js SDK using npm and use it to recognize a song from a URL. Replace 'your-api-token' with your actual API token.

```bash
npm install @audd/sdk
```

```typescript
const audd = new AudD("your-api-token");
const song = await audd.recognize("https://audd.tech/example.mp3");
console.log(`${song.artist} — ${song.title}`);
```

--------------------------------

### Recognize Audio and Get Streaming Service Metadata

Source: https://docs.audd.io/sdks/c

This example demonstrates how to recognize an audio file from a URL and retrieve metadata for specific streaming services like Apple Music and Spotify. It also shows how to get a direct streaming URL or a preview URL.

```APIDOC
## Recognize Audio and Get Streaming Service Metadata

Pass `return_metadata` to populate provider sub-objects on the result. Without it, those blocks are NULL.

```c
const char *want[] = { "apple_music", "spotify", NULL };
audd_recognize_options_t opts = { .return_metadata = want };

audd_recognition_t *r = NULL;
audd_error_t e = audd_recognize(client, "https://audd.tech/example.mp3", &opts, &r);

if (e == AUDD_OK && r != NULL) {
    const audd_apple_music_t *am = audd_recognition_apple_music(r);
    if (am) printf("Apple Music: %s\n", audd_apple_music_get_url(am));

    const audd_spotify_t *sp = audd_recognition_spotify(r);
    if (sp) printf("Spotify URI: %s\n", audd_spotify_get_uri(sp));

    /* Or resolve any provider — direct URL when the metadata block is set,
       else the lis.tn redirect when song_link is on lis.tn. */
    printf("%s\n", audd_recognition_streaming_url(r, AUDD_PROVIDER_SPOTIFY));
    printf("preview: %s\n", audd_recognition_preview_url(r));

    audd_recognition_free(r);
}
```

Valid providers (the strings in `return_metadata`): `apple_music`,
`spotify`, `deezer`, `napster`, `musicbrainz`. Each adds latency.
The `audd_provider_t` enum (used by `audd_recognition_streaming_url`) 
covers `SPOTIFY`, `APPLE_MUSIC`, `DEEZER`, `NAPSTER`, `YOUTUBE`.

The `market` option (ISO 3166 region code) controls the Apple Music
storefront:

```c
audd_recognize_options_t opts = { .return_metadata = want, .market = "GB" };
```

For each provider sub-object's full field shape, see [the upstream API
reference](/) and [the GitHub README](https://github.com/AudDMusic/audd-c#what-you-get-back).
```

--------------------------------

### Quick Start API Request

Source: https://docs.audd.io/.md

This is a basic example of how to make a request to the AudD API using curl to identify a song from a given URL. Ensure you have an API token from the AudD dashboard.

```bash
curl https://api.audd.io/ \
  -F url='https://audd.tech/example.mp3' \
  -F api_token='test'
```

--------------------------------

### Basic Recognition Example

Source: https://docs.audd.io/sdks/kotlin

Demonstrates how to initialize the AudD client and recognize a song from a URL.

```APIDOC
## Recognize Song

### Description
Recognizes a song from a given audio URL.

### Method
`suspend fun recognize(url: String): Song?`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```kotlin
fun main() = runBlocking {
    AudD("your-api-token").use {\n        val song = audd.recognize("https://audd.tech/example.mp3")\n        println("${song?.artist} — ${song?.title}")\n    }\n}
```

### Response
#### Success Response (200)
Returns a `Song` object containing artist and title information, or null if recognition fails.

#### Response Example
```json
{
  "artist": "Example Artist",
  "title": "Example Song Title"
}
```
```

--------------------------------

### Basic Recognition

Source: https://docs.audd.io/sdks/node

Installs the SDK and performs a basic music recognition using a provided audio URL.

```APIDOC
## Basic Recognition

### Description
Installs the SDK and performs a basic music recognition using a provided audio URL.

### Installation
```bash
npm install @audd/sdk
```

### Usage
```typescript
// get a real token at dashboard.audd.io; "test" is capped at 10 req/day
const audd = new AudD("test");
const song = await audd.recognize("https://audd.tech/example.mp3");
if (song) console.log(`${song.artist} — ${song.title}`);
```
```

--------------------------------

### Add AudD .NET Package

Source: https://docs.audd.io/sdks

Install the AudD .NET package using the dotnet CLI.

```bash
dotnet add package AudD
```

--------------------------------

### Quick Start: Identify Song from URL

Source: https://docs.audd.io/

This example demonstrates how to identify a song from a given URL using the AudD API. Ensure you have an API token.

```curl
curl https://api.audd.io/ \
  -F url='https://audd.tech/example.mp3' \
  -F api_token='test'  

```

--------------------------------

### Standard Recognition - Quick Example

Source: https://docs.audd.io/

This example demonstrates how to perform standard song identification using the AudD API with a provided audio URL and API token.

```APIDOC
## Standard Recognition - Quick Example

### Description
This endpoint is best for single song identification and processes audio files up to 12 seconds with a response time of approximately 0.1-1.5 seconds.

### Method
POST

### Endpoint
https://api.audd.io/

### Parameters
#### Query Parameters
- **api_token** (string) - Required - The authentication token for API requests. Sign up on the Dashboard to get one.

#### Request Body
- **url** (string) - Required - The URL of the audio file to identify.

### Request Example
```curl
https://api.audd.io/ \
  -F url='https://audd.tech/example.mp3' \
  -F api_token='test'
```

### Response
#### Success Response (200)
- **field1** (type) - Description
```

--------------------------------

### Install audd-php using Composer

Source: https://docs.audd.io/sdks/php

Use Composer to install the audd-php SDK. This command adds the library to your project dependencies.

```bash
composer require audd/audd
```

--------------------------------

### Recognize Song (Kotlin)

Source: https://docs.audd.io/

Example of recognizing a song using Kotlin.

```APIDOC
## Recognize Song (Kotlin)

### Description
Recognizes a song from an audio file using Kotlin.

### Method
```kotlin
audd.recognize(Source.FilePath(File(path)))
```

### Parameters
- `apiToken` (String) - Your Audd.io API token.
- `path` (String) - The path to the audio file.

### Request Example
```kotlin
val audd = AudD("your-api-token")
val song = audd.recognize(Source.FilePath(File("/path/to/clip.mp3")))
println("${song?.artist} — ${song?.title}")
```

### Response
#### Success Response
Returns a `Song` object containing artist and title if recognized.

#### Response Example
```
Artist Name — Song Title
```
```

--------------------------------

### Install and Use Rust SDK

Source: https://docs.audd.io/sdks

Add the Rust SDK to your project and use it to recognize a song from a URL. Replace 'your-api-token' with your actual API token.

```bash
cargo add audd
```

```rust
use audd::AudD;

let audd = AudD::new("your-api-token");
let r = audd.recognize("https://audd.tech/example.mp3").await?;
if let Some(song) = r {
    println!("{} — {}",
        song.artist.as_deref().unwrap_or(""),
        song.title.as_deref().unwrap_or(""));
}
```

--------------------------------

### Recognize Music using Audd.io SDK (Go)

Source: https://docs.audd.io/

Example of how to recognize music using the Audd.io Go SDK.

```APIDOC
## Recognize Music using Audd.io SDK (Go)

### Description
This method uses the Audd.io Go SDK to recognize music from an audio file.

### Method
`Recognize`

### Parameters
- **file** (os.File) - Required - The audio file to recognize.
- **options** (*RecognizeOptions) - Optional - Recognition options, such as `ReturnMetadata`.

### Request Example
```go
package main

import (
    "fmt"
    "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/example.mp3")
    if err != nil {
        log.Fatal(err)
    }
    defer f.Close()

    result, err := client.Recognize(f, &audd.RecognizeOptions{
        ReturnMetadata: "apple_music,spotify",
    })
    if err != nil {
        log.Fatal(err)
    }
    if result == nil {
        fmt.Println("no match")
        return
    }

    // Always-present fields.
    fmt.Printf("%s — %s\n", result.Artist, result.Title)
    fmt.Println("Album:      ", result.Album)
    fmt.Println("Released:   ", result.ReleaseDate)
    fmt.Println("Label:      ", result.Label)
    fmt.Println("Timecode:   ", result.Timecode)
    fmt.Println("AudD link:  ", result.SongLink)

    // Helpers — work without any Return opt-in.
    fmt.Println("Thumbnail:  ", result.ThumbnailURL())
    fmt.Println("Preview:    ", result.PreviewURL())
    fmt.Println("On Spotify: ", result.StreamingURL(audd.ProviderSpotify))

    // Provider blocks — populated only when requested via Return.
    if result.AppleMusic != nil {
        fmt.Println("Apple Music URL:", result.AppleMusic.URL)
    }
    if result.Spotify != nil {
        fmt.Println("Spotify URI:    ", result.Spotify.URI)
    }
    if result.Deezer != nil {
        fmt.Println("Deezer link:    ", result.Deezer.Link)
    }
    if result.Napster != nil {
        fmt.Println("Napster ID:     ", result.Napster.ID)
    }
    if len(result.MusicBrainz) > 0 {
        fmt.Println("MusicBrainz ID: ", result.MusicBrainz[0].ID)
    }
}
```
```

--------------------------------

### Recognize Song (C SDK)

Source: https://docs.audd.io/

Example of recognizing a song using the C SDK.

```APIDOC
## Recognize Song (C SDK)

### Description
Recognizes a song from an audio file using the Audd.io C SDK.

### Method
```c
audd_recognize(client, source, options, &result)
```

### Parameters
- `client` (*audd_client_t): Pointer to the Audd client.
- `source` (audd_source_t): Source of the audio (e.g., file path).
- `options` (const char*): Optional parameters.
- `result` (**audd_recognition_result_t): Pointer to store the recognition result.

### Request Example
```c
audd_client_t* client = audd_client_new("your-api-token", NULL);
audd_recognition_result_t* result = NULL;
audd_recognize(client, audd_source_path("/path/to/clip.mp3"), NULL, &result);
printf("%s — %s\n", result->artist, result->title);
audd_recognition_result_free(result);
audd_client_free(client);
```

### Response
#### Success Response
Populates the `result` structure with artist and title if recognized.

#### Response Example
```c
Artist Name — Song Title
```
```

--------------------------------

### Recognize Song (C#)

Source: https://docs.audd.io/

Example of recognizing a song using C# with OkHttp.

```APIDOC
## Recognize Song (C#)

### Description
Recognizes a song from an audio file using C# with OkHttp.

### Method
`POST https://api.audd.io/`

### Parameters
#### Request Body
- `api_token` (string) - Required - Your Audd.io API token.
- `file` (file) - Required - The audio file to recognize.
- `return` (string) - Optional - Comma-separated identifiers for additional metadata (e.g., `apple_music,spotify`).

### Request Example
```csharp
// requires OkHttp
using var audd = new AudD("your-api-token");
var song = await audd.RecognizeAsync("/path/to/clip.mp3");
Console.WriteLine($"{song.Artist} — {song.Title}");
```

### Response
#### Success Response
Returns a `RecognitionResult` object containing artist and title.

#### Response Example
```csharp
{
  "artist": "Artist Name",
  "title": "Song Title"
}
```
```

--------------------------------

### Recognize Song (Go SDK)

Source: https://docs.audd.io/

Example of recognizing a song from an audio file using the Go SDK.

```APIDOC
## Recognize Song (Go SDK)

### Description
Recognizes a song from a given audio file path using the Go SDK.

### Method
```go
client.recognize(path)
```

### Parameters
- `path` (*std::path::Path): The path to the audio file.

### Request Example
```go
let client = audd::Client::builder().api_token("your-api-token").build()?;
let result = client.recognize(std::path::Path::new("/path/to/clip.mp3")).await?;
if let Some(song) = result {
    println!("{} — {}", song.artist, song.title);
}
```

### Response
#### Success Response
Returns a `Song` object containing artist and title if recognized, otherwise `None`.

#### Response Example
```
Artist Name — Song Title
```
```

--------------------------------

### Recognize Music using Audd.io SDK (C++)

Source: https://docs.audd.io/

Example of how to recognize music using the Audd.io C++ SDK.

```APIDOC
## Recognize Music using Audd.io SDK (C++)

### Description
This method uses the Audd.io C++ SDK to recognize music from an audio file URL.

### Method
`recognize`

### Parameters
- **source** (audd::Source) - Required - Source of the audio (e.g., URL).

### Request Example
```cpp
audd::AudD client("your-api-token");
auto song = client.recognize(audd::Source::url("https://audd.tech/example.mp3"));
if (song) std::cout << song->artist << " — " << song->title << "\n";
```
```

--------------------------------

### Recognize Song (Java SDK)

Source: https://docs.audd.io/

Example of recognizing a song using the Java SDK.

```APIDOC
## Recognize Song (Java SDK)

### Description
Recognizes a song from an audio file using the Audd.io Java SDK.

### Method
```java
try (AudD audd = new AudD("your-api-token")) {
    RecognitionResult song = audd.recognize(Path.of("/path/to/clip.mp3"));
    System.out.println(song.artist() + " — " + song.title());
}
```

### Parameters
- `apiToken` (String) - Your Audd.io API token.
- `path` (Path) - The path to the audio file.

### Request Example
```java
try (AudD audd = new AudD("your-api-token")) {
    RecognitionResult song = audd.recognize(Path.of("/path/to/clip.mp3"));
    System.out.println(song.artist() + " — " + song.title());
}
```

### Response
#### Success Response
Returns a `RecognitionResult` object containing artist and title.

#### Response Example
```java
{
  "artist": "Artist Name",
  "title": "Song Title"
}
```
```

--------------------------------

### Recognize Song (PHP SDK)

Source: https://docs.audd.io/

Example of recognizing a song using the PHP SDK.

```APIDOC
## Recognize Song (PHP SDK)

### Description
Recognizes a song from an audio file using the Audd.io PHP SDK.

### Method
```php
$audd->recognize(filePath)
```

### Parameters
- `filePath` (string) - The path to the audio file.
- `apiToken` (string) - Your Audd.io API token (provided during client initialization).

### Request Example
```php
$audd = new AudD\AudD('your-api-token');
$song = $audd->recognize('/path/to/clip.mp3');
echo "{$song->artist} — {$song->title}\n";
```

### Response
#### Success Response
Returns a `Song` object containing artist and title if recognized.

#### Response Example
```
Artist Name — Song Title
```
```

--------------------------------

### Recognize Song (C++ SDK)

Source: https://docs.audd.io/

Example of recognizing a song using the C++ SDK.

```APIDOC
## Recognize Song (C++ SDK)

### Description
Recognizes a song from an audio file using the Audd.io C++ SDK.

### Method
```cpp
client.recognize(source)
```

### Parameters
- `apiToken` (string) - Your Audd.io API token.
- `source` (audd::Source) - The source of the audio, e.g., `audd::Source::path(string)`.

### Request Example
```cpp
audd::AudD client("your-api-token");
auto song = client.recognize(audd::Source::path("/path/to/clip.mp3"));
if (song) std::cout << song->artist << " — " << song->title << "\n";
```

### Response
#### Success Response
Returns a pointer to a `Song` object containing artist and title if recognized.

#### Response Example
```cpp
Artist Name — Song Title
```
```

--------------------------------

### Recognize Music using Audd.io SDK (C)

Source: https://docs.audd.io/

Example of how to recognize music using the Audd.io C SDK.

```APIDOC
## Recognize Music using Audd.io SDK (C)

### Description
This method uses the Audd.io C SDK to recognize music from an audio file URL.

### Method
`audd_recognize`

### Parameters
- **client** (audd_client_t*) - Required - Pointer to the Audd client.
- **source** (audd_source_t*) - Required - Source of the audio (e.g., URL).
- **options** (audd_recognition_options_t*) - Optional - Recognition options.
- **result** (audd_recognition_result_t**) - Output - Pointer to store the recognition result.

### Request Example
```c
audd_client_t* client = audd_client_new("your-api-token", NULL);
audd_recognition_result_t* result = NULL;
audd_recognize(client, audd_source_url("https://audd.tech/example.mp3"), NULL, &result);
printf("%s — %s\n", result->artist, result->title);
audd_recognition_result_free(result);
audd_client_free(client);
```
```

--------------------------------

### Recognize Music using Audd.io SDK (Python)

Source: https://docs.audd.io/

Example of how to recognize music using the official Audd.io Python SDK.

```APIDOC
## Recognize Music using Audd.io SDK (Python)

### Description
This method uses the Audd.io Python SDK to recognize music from an audio file.

### Method
`recognize`

### Parameters
- **audio_file** (file-like object or bytes) - Required - The audio file to recognize.

### Request Example
```python
from audd import AudD

audd = AudD("your-api-token")
with open("/path/to/clip.mp3", "rb") as f:
    result = audd.recognize(f)
print(f"{result.artist} — {result.title}")
```
```

--------------------------------

### Recognize Music using Audd.io SDK (Node.js)

Source: https://docs.audd.io/

Example of how to recognize music using the official Audd.io Node.js SDK.

```APIDOC
## Recognize Music using Audd.io SDK (Node.js)

### Description
This method uses the Audd.io Node.js SDK to recognize music from an audio file buffer.

### Method
`recognize`

### Parameters
- **audio_buffer** (Buffer) - Required - The audio file buffer to recognize.

### Request Example
```javascript
import { AudD } from "@audd/sdk";
import { readFile } from "node:fs/promises";

const audd = new AudD("your-api-token");
const buf = await readFile("/path/to/clip.mp3");
const song = await audd.recognize(buf);
console.log(`${song.artist} — ${song.title}`);
```
```

--------------------------------

### Recognize Music using Audd.io SDK (Java)

Source: https://docs.audd.io/

Example of how to recognize music using the Audd.io Java SDK.

```APIDOC
## Recognize Music using Audd.io SDK (Java)

### Description
This method uses the Audd.io Java SDK to recognize music from an audio file URL.

### Method
`recognize`

### Parameters
- **url** (String) - Required - The URL of the audio file to recognize.

### Request Example
```java
// requires OkHttp
OkHttpClient client = new OkHttpClient();
RequestBody data = new MultipartBody.Builder().setType(MultipartBody.FORM)
    .addFormDataPart("api_token", "your api token")
    .addFormDataPart("url", "https://audd.tech/example.mp3")
    .addFormDataPart("return", "apple_music,spotify").build();
Request request = new Request.Builder().url("https://api.audd.io/")
    .post(data).build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());

```

**Or with the SDK:**
```java
try (AudD audd = new AudD("your-api-token")) {
    RecognitionResult song = audd.recognize("https://audd.tech/example.mp3");
    System.out.println(song.artist() + " — " + song.title());
}
```
```

--------------------------------

### Recognize Song (Direct GET Request)

Source: https://docs.audd.io/

Example of recognizing a song using a direct GET request to the Audd.io API.

```APIDOC
## Recognize Song (Direct GET Request)

### Description
Recognizes a song by sending a GET request to the Audd.io API. Parameters should be URL-encoded.

### Method
`GET https://api.audd.io/`

### Parameters
#### Query Parameters
- `url` (string) - Required - The URL of the audio file.
- `return` (string) - Optional - Comma-separated identifiers for additional metadata (e.g., `apple_music,spotify`).
- `api_token` (string) - Required - Your Audd.io API token.

### Request Example
```
https://api.audd.io/?url=https://audd.tech/example1.mp3&return=apple_music,spotify&api_token=your%20api%20token
```

### Response
#### Success Response
Returns a JSON object containing recognition results.

#### Response Example
```json
{
  "artist": "Artist Name",
  "title": "Song Title"
}
```
```

--------------------------------

### Recognize Audio with C SDK

Source: https://docs.audd.io/

This C example shows how to use the Audd.io C SDK to recognize audio. It involves creating a client, calling the recognize function with a file path, and printing the results.

```c
audd_client_t* client = audd_client_new("your-api-token", NULL);  
audd_recognition_result_t* result = NULL;  
audd_recognize(client, audd_source_path("/path/to/clip.mp3"), NULL, &result);  
printf("%s — %s\n", result->artist, result->title);  
audd_recognition_result_free(result);  
audd_client_free(client);  


```

--------------------------------

### Recognize Audio with Go SDK

Source: https://docs.audd.io/

Use the Go SDK to build a client, authenticate with an API token, and recognize audio from a file path. Handles potential errors during the process.

```go
let client = audd::Client::builder().api_token("your-api-token").build()?;  
let result = client.recognize(std::path::Path::new("/path/to/clip.mp3")).await?;  
if let Some(song) = result {  
    println!("{} — {}", song.artist, song.title);  
}  

```

--------------------------------

### Long Poll Request Example

Source: https://docs.audd.io/streams

An example of a LongPoll URL for receiving real-time updates. The `since_time` parameter should be updated with the `timestamp` from the previous response.

```text
https://api.audd.io/longpoll/?category=92b1cc7f0&timeout=50&since_time=1652123144400
```

--------------------------------

### Initialize Client with Configuration

Source: https://docs.audd.io/sdks/cpp

Instantiate the AudD client with a configuration object. Set fields on the ClientConfig struct before passing it to the constructor.

```cpp
audd::ClientConfig cfg;
// ... set fields ...
audd::AudD client("your-api-token", cfg);
```

--------------------------------

### Client Initialization

Source: https://docs.audd.io/sdks/go.md

Demonstrates different ways to initialize the audd-go client, including using an explicit token, an environment variable, or strict initialization that fails fast on missing tokens.

```APIDOC
## Client Initialization

### Description
Initializes the audd-go client with an API token. Supports explicit token passing, environment variables, and strict initialization.

### Method
`NewClient(apiToken string)`
`NewClientStrict(apiToken string) (*Client, error)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
// Explicit token
client := audd.NewClient("your-api-token")

// Using AUDD_API_TOKEN environment variable
// AUDD_API_TOKEN=your-token go run main.go
client := audd.NewClient("")

// Strict initialization (fails fast if token is missing)
client, err := audd.NewClientStrict("")
if errors.Is(err, audd.ErrMissingAPIToken) {
    log.Fatal("set AUDD_API_TOKEN or pass a token to NewClient")
}
```

### Response
#### Success Response (200)
- **Client** (*audd.Client) - An initialized client instance.

#### Response Example
None
```

--------------------------------

### GET Request for Music Recognition

Source: https://docs.audd.io/.md

This snippet demonstrates a GET request to the Audd.io API. Parameters must be URL-encoded. It's recommended to use POST requests for better performance.

```http
https://api.audd.io/?url=https://audd.tech/example1.mp3&return=apple_music,spotify&api_token=your%20api%20token
```

--------------------------------

### Client Initialization

Source: https://docs.audd.io/sdks/c

Demonstrates how to initialize the AUDD client with an API token, either explicitly or via an environment variable. It also shows how to use `audd_client_new_strict` for immediate error checking.

```APIDOC
## Client Initialization

### Description
Initialize the AUDD client with an API token. The token can be provided directly as an argument, read from the `AUDD_API_TOKEN` environment variable, or result in an `AUDD_ERR_AUTHENTICATION` error if not found.

### Usage
```c
audd_client_t *client = audd_client_new("your-api-token", NULL); /* explicit */
audd_client_t *client = audd_client_new(NULL, NULL);             /* AUDD_API_TOKEN */
```

### Strict Initialization
For immediate error checking during construction, use `audd_client_new_strict`.

### Usage
```c
audd_error_t err = AUDD_OK;
audd_client_t *client = audd_client_new_strict(NULL, NULL, &err);
if (client == NULL) {
    fprintf(stderr, "audd: %s\n", audd_error_string(err));
    return 1;
}
```
```

--------------------------------

### C SDK Longpoll Example with Callbacks

Source: https://docs.audd.io/sdks/c

A complete C example demonstrating how to set up and run a longpolling client for stream events. It includes callback functions for matches, notifications, and errors, and handles SIGINT for graceful shutdown.

```c
static audd_longpoll_t *g_handle;

static void on_match(const audd_stream_callback_match_t *m, void *ud)
{
    const audd_stream_callback_song_t *s = audd_stream_callback_match_get_song(m);
    printf("matched: %s — %s\n",
           audd_stream_callback_song_get_artist(s),
           audd_stream_callback_song_get_title(s));
}

static void on_notification(const audd_stream_callback_notification_t *n, void *ud)
{
    printf("notification: %s\n",
           audd_stream_callback_notification_get_message(n));
}

static void on_error(audd_error_t err, const char *msg, void *ud)
{
    fprintf(stderr, "terminal: %s — %s\n", audd_error_string(err), msg);
}

static void on_sigint(int sig) { audd_longpoll_close(g_handle); }

int main(void)
{
    audd_client_t *client = audd_client_new(NULL, NULL); /* reads AUDD_API_TOKEN */
    if (!client) return 1;

    int radio_id = 1; /* any integer you choose — your handle for this stream */

    audd_longpoll_callbacks_t cb = {
        .on_match        = on_match,
        .on_notification = on_notification,
        .on_error        = on_error,
        .user_data       = NULL,
    };
    signal(SIGINT, on_sigint);

    audd_error_t rc = audd_longpoll_run_by_radio_id(
        client, radio_id, NULL, &cb, &g_handle);
    if (rc != AUDD_OK) {
        fprintf(stderr, "longpoll failed: %s\n", audd_error_string(rc));
    }
    /* Blocks until on_error fires or audd_longpoll_close is called.
       The handle is freed automatically on return — don't use it after. */

    audd_client_free(client);
    return 0;
}
```

--------------------------------

### Initialize Client with Environment Variable

Source: https://docs.audd.io/sdks/go.md

Initialize the audd-go client without arguments, allowing it to pick up the API token from the AUDD_API_TOKEN environment variable.

```go
// AUDD_API_TOKEN=your-token  go run main.go
client := audd.NewClient("")
```

--------------------------------

### Recognize music with Go SDK

Source: https://docs.audd.io/

Use the official Go SDK for Audd.io to recognize music from a URL. This example shows how to initialize the client and make a recognition request.

```go
package main

import (
    "fmt"
    "log"

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

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

    result, err := client.Recognize("https://audd.tech/example.mp3", &audd.RecognizeOptions{
        ReturnMetadata: "apple_music,spotify",
    })
    if err != nil {
        log.Fatal(err)
    }
    if result == nil {
        fmt.Println("no match")
        return
    }

    // Always-present fields.
    fmt.Printf("%s — %s\n", result.Artist, result.Title)
    fmt.Println("Album:      ", result.Album)
    fmt.Println("Released:   ", result.ReleaseDate)
    fmt.Println("Label:      ", result.Label)
    fmt.Println("Timecode:   ", result.Timecode)
    fmt.Println("AudD link:  ", result.SongLink)

    // Helpers — work without any Return opt-in.
    fmt.Println("Thumbnail:  ", result.ThumbnailURL())
    fmt.Println("Preview:    ", result.PreviewURL())
    fmt.Println("On Spotify: ", result.StreamingURL(audd.ProviderSpotify))

    // Provider blocks — populated only when requested via Return.
    if result.AppleMusic != nil {
        fmt.Println("Apple Music URL:", result.AppleMusic.URL)
    }
    if result.Spotify != nil {
        fmt.Println("Spotify URI:    ", result.Spotify.URI)
    }
    if result.Deezer != nil {
        fmt.Println("Deezer link:    ", result.Deezer.Link)
    }
    if result.Napster != nil {
        fmt.Println("Napster ID:     ", result.Napster.ID)
    }
    if len(result.MusicBrainz) > 0 {
        fmt.Println("MusicBrainz ID: ", result.MusicBrainz[0].ID)
    }
}
```

--------------------------------

### Recognize Audio with Kotlin SDK

Source: https://docs.audd.io/

Use the Kotlin SDK to recognize audio by providing your API token and the file path. This example demonstrates basic usage and output.

```kotlin
val audd = AudD("your-api-token")  
val song = audd.recognize(Source.FilePath(File("/path/to/clip.mp3")))  
println("${song?.artist} — ${song?.title}")  


```

--------------------------------

### Recognize Song (Swift)

Source: https://docs.audd.io/

Example of recognizing a song using Swift.

```APIDOC
## Recognize Song (Swift)

### Description
Recognizes a song from an audio file using Swift.

### Method
```swift
await audd.recognize(.file(file))
```

### Parameters
- `apiToken` (string) - Your Audd.io API token.
- `file` (URL) - The URL of the audio file.

### Request Example
```swift
let audd = try AudD(apiToken: "your-api-token")
let file = URL(fileURLWithPath: "/path/to/clip.mp3")
if let song = try await audd.recognize(.file(file)) {
    print("\(song.artist) — \(song.title)")
}
```

### Response
#### Success Response
Returns a `Song` object containing artist and title if recognized.

#### Response Example
```
Artist Name — Song Title
```
```

--------------------------------

### Recognize Audio with Java SDK

Source: https://docs.audd.io/

Use the Java SDK for Audd.io to recognize audio from a file path. This example demonstrates initializing the SDK and handling the recognition result.

```java
try (AudD audd = new AudD("your-api-token")) {  
    RecognitionResult song = audd.recognize(Path.of("/path/to/clip.mp3"));  
    System.out.println(song.artist() + " — " + song.title());  
}  


```

--------------------------------

### AudD Client Initialization

Source: https://docs.audd.io/sdks/php

Demonstrates different ways to initialize the AudD client, including explicit token passing, reading from environment variables, and using a static factory method.

```APIDOC
## AudD Client Initialization

### Description
Initialize the AudD client with your API token. The token can be provided directly, read from an environment variable, or obtained using a static method.

### Method
Constructor / Static Method

### Endpoint
Not applicable (SDK initialization)

### Parameters
#### Constructor
- **api_token** (string) - Optional - Your API token. If not provided, it attempts to read from the `AUDD_API_TOKEN` environment variable.

#### Static Method `fromEnvironment()`
No parameters.

### Request Example
```php
<?php

use AudD\AudD;

// Explicitly provide the API token
$audd = new AudD('your-api-token');

// Read API token from AUDD_API_TOKEN environment variable
$audd = new AudD();

// Use the static method to read from environment variable
$audd = AudD::fromEnvironment();
?>
```

### Response
- **AudD Client Instance** - An instance of the AudD client is returned upon successful initialization.
```

--------------------------------

### Manage SDK Lifecycle with Context Manager (Synchronous)

Source: https://docs.audd.io/sdks/python

Use the `AudD` client as a context manager (`with` statement) to ensure proper release of HTTP resources. This is the recommended way to manage the client's lifecycle.

```python
with AudD() as audd:
    result = audd.recognize("https://audd.tech/example.mp3")
```

--------------------------------

### Add a Stream using Java (OkHttp)

Source: https://docs.audd.io/streams

Example of adding a stream using OkHttp in Java. This code snippet demonstrates setting up the request with multipart form data.

```java
// requires OkHttp 
public static void main() {
try {
OkHttpClient client = new OkHttpClient();
RequestBody data = new MultipartBody.Builder().setType(MultipartBody.FORM)
    .addFormDataPart("url", "https://npr-ice.streamguys1.com/live.mp3")
    .addFormDataPart("radio_id", "3249")
    .addFormDataPart("api_token", "your api token").build();
Request request = new Request.Builder().url("https://api.audd.io/addStream/")
    .post(data).build();
Response response = null;
response = client.newCall(request).execute();
String result = null;
result = response.body().string();
System.out.println(result);
} catch (Exception e) {
e.printStackTrace();
}
//Thanks to Yaniv Levy and Adam Cole for the help
}
```

--------------------------------

### Use AudD with Default Configuration

Source: https://docs.audd.io/sdks/dotnet

Instantiate `AudD` with the default configuration using `await using` for proper asynchronous disposal. This is the recommended pattern for managing the SDK's lifecycle.

```csharp
await using var audd = new AudD("your-api-token");
var result = await audd.RecognizeAsync("https://audd.tech/example.mp3");
```

--------------------------------

### Send a file URL (C++)

Source: https://docs.audd.io/

Example of sending a file URL to the Audd.io API using C++.

```APIDOC
## Send a file URL (C++)

### Description
Send a file URL to the Audd.io API for audio recognition using C++. This typically involves using a library like libcurl or cpprestsdk.

### Method
POST

### Endpoint
https://api.audd.io/

### Parameters
#### Request Body
- **api_token** (string) - Required - Your Audd.io API token.
- **url** (string) - Required - The URL of the audio file.
- **return** (string) - Optional - Comma-separated list of metadata to return (e.g., 'apple_music,spotify').

### Request Example
```cpp
// Example using libcurl (conceptual):
// #include <curl/curl.h>
// ...
// CURL *curl = curl_easy_init();
// if(curl) {
//     curl_easy_setopt(curl, CURLOPT_URL, "https://api.audd.io/");
//     curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "api_token=your_api_token&url=https://audd.tech/example.mp3&return=apple_music,spotify");
//     // ... other options and execution ...
//     curl_easy_cleanup(curl);
// }
```

### Response
#### Success Response (200)
- **artist** (string) - The artist of the recognized song.
- **title** (string) - The title of the recognized song.
- **album** (string) - The album of the recognized song.
- **release_date** (string) - The release date of the album.
- **label** (string) - The record label.
- **timecode** (string) - The timecode within the audio file where the recognition occurred.
- **song_link** (string) - A link to the song on Audd.io.
- **thumbnail_url** (string) - URL for the song's thumbnail.
- **preview_url** (string) - URL for a preview of the song.
- **streaming_url** (object) - Object containing streaming URLs for different platforms.
- **apple_music** (object) - Apple Music metadata if requested.
- **spotify** (object) - Spotify metadata if requested.
- **deezer** (object) - Deezer metadata if requested.
- **napster** (object) - Napster metadata if requested.
- **music_brainz** (array) - MusicBrainz data if available.

### Response Example
```json
{
  "artist": "Example Artist",
  "title": "Example Song",
  "album": "Example Album",
  "release_date": "2023-01-01",
  "label": "Example Label",
  "timecode": "00:15",
  "song_link": "https://audd.io/song/example-song",
  "thumbnail_url": "https://example.com/thumbnail.jpg",
  "preview_url": "https://example.com/preview.mp3",
  "streaming_url": {
    "spotify": "https://open.spotify.com/track/example"
  },
  "apple_music": {
    "url": "https://music.apple.com/us/album/example-song/123456789"
  },
  "spotify": {
    "uri": "spotify:track:example"
  },
  "deezer": {
    "link": "https://www.deezer.com/track/example"
  },
  "napster": {
    "id": "example_napster_id"
  },
  "music_brainz": [
    {
      "id": "example_musicbrainz_id"
    }
  ]
}
```
```

--------------------------------

### Initialize Client with Explicit Token

Source: https://docs.audd.io/sdks/go.md

Create a new audd-go client instance by explicitly providing your API token.

```go
// Explicit.
client := audd.NewClient("your-api-token")
```

--------------------------------

### Instantiate audd::AudD Client with API Token

Source: https://docs.audd.io/sdks/cpp

Shows two ways to initialize the audd::AudD client: by explicitly passing an API token to the constructor or by allowing it to read the token from the AUDD_API_TOKEN environment variable.

```cpp
audd::AudD client("your-api-token");  // explicit
audd::AudD client_env("");            // reads AUDD_API_TOKEN
```

--------------------------------

### Send a file URL (C)

Source: https://docs.audd.io/

Example of sending a file URL to the Audd.io API using C.

```APIDOC
## Send a file URL (C)

### Description
Send a file URL to the Audd.io API for audio recognition using C. This typically involves using a library like libcurl.

### Method
POST

### Endpoint
https://api.audd.io/

### Parameters
#### Request Body
- **api_token** (string) - Required - Your Audd.io API token.
- **url** (string) - Required - The URL of the audio file.
- **return** (string) - Optional - Comma-separated list of metadata to return (e.g., 'apple_music,spotify').

### Request Example
```c
// Example using libcurl (conceptual):
// #include <curl/curl.h>
// ...
// CURL *curl = curl_easy_init();
// if(curl) {
//     curl_easy_setopt(curl, CURLOPT_URL, "https://api.audd.io/");
//     curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "api_token=your_api_token&url=https://audd.tech/example.mp3&return=apple_music,spotify");
//     // ... other options and execution ...
//     curl_easy_cleanup(curl);
// }
```

### Response
#### Success Response (200)
- **artist** (string) - The artist of the recognized song.
- **title** (string) - The title of the recognized song.
- **album** (string) - The album of the recognized song.
- **release_date** (string) - The release date of the album.
- **label** (string) - The record label.
- **timecode** (string) - The timecode within the audio file where the recognition occurred.
- **song_link** (string) - A link to the song on Audd.io.
- **thumbnail_url** (string) - URL for the song's thumbnail.
- **preview_url** (string) - URL for a preview of the song.
- **streaming_url** (object) - Object containing streaming URLs for different platforms.
- **apple_music** (object) - Apple Music metadata if requested.
- **spotify** (object) - Spotify metadata if requested.
- **deezer** (object) - Deezer metadata if requested.
- **napster** (object) - Napster metadata if requested.
- **music_brainz** (array) - MusicBrainz data if available.

### Response Example
```json
{
  "artist": "Example Artist",
  "title": "Example Song",
  "album": "Example Album",
  "release_date": "2023-01-01",
  "label": "Example Label",
  "timecode": "00:15",
  "song_link": "https://audd.io/song/example-song",
  "thumbnail_url": "https://example.com/thumbnail.jpg",
  "preview_url": "https://example.com/preview.mp3",
  "streaming_url": {
    "spotify": "https://open.spotify.com/track/example"
  },
  "apple_music": {
    "url": "https://music.apple.com/us/album/example-song/123456789"
  },
  "spotify": {
    "uri": "spotify:track:example"
  },
  "deezer": {
    "link": "https://www.deezer.com/track/example"
  },
  "napster": {
    "id": "example_napster_id"
  },
  "music_brainz": [
    {
      "id": "example_musicbrainz_id"
    }
  ]
}
```
```