AudD Music Recognition

Use this only when the user asks to start monitoring a radio or live stream. AudD then recognizes the stream continuously and sends results to the callback URL: by default after each song ends, or as soon as a song starts with callbacks="before" (those results have no play length). radio_id is the user's own integer for the stream and must be unique on the account. The account's streams plan needs a free stream slot.

add_stream

Use this only when the user asks to change the URL of a stream they already monitor. It replaces that stream's URL; recognition continues on the new URL under the same radio_id.

update_stream_url

Use this only when the user asks to stop monitoring a stream. AudD stops recognizing it and removes it from the account; this cannot be undone (add the stream again to resume).

delete_stream

Use this when the user asks about their AudD plan or subscription status. Returns the plan name and its included requests per billing period, the status (active, trial, lapsed, lapsed_settled = lapsed with nothing owed, or banned), the paid-until date, bonus requests and whether the plan renews automatically. Read-only.

get_account_status

Use this when the user asks whether they owe anything for usage beyond their plan. Returns the requests used beyond the plan's included allowance in the current billing period and what they cost in cents; AudD bills that amount at the end of the billing period. Read-only.

get_amount_owed

Use this when the user asks about past payments on their AudD account. Returns paid charges only, newest first: the date paid, the amount in cents, and what it was for (subscription_start or subscription_renewal; extra_requests_settle = requests beyond the plan's allowance; bonus_requests_purchase = requests bought in advance; streams = stream monitoring). Read-only.

get_billing_history

Use this when the user asks where AudD sends their stream recognition results. Returns the account's callback URL, or null when AudD reports that none is set (a temporary AudD error can look the same, so confirm with the user before replacing it). Read-only.

get_stream_callback_url

Use this when the user asks how many AudD requests they have used. Returns the current billing period's total, allowance and remaining requests, and daily request counts (totals only); with "days", daily counts for the last N days instead. Read-only.

get_usage_stats

Use this when the user wants to know which song is in an audio or video file at a public URL (a direct link to the file, such as an .mp3). Only the first 12 seconds of the audio are analyzed, so it returns at most one song. Returns the artist, title, album, release date, label and a song link, plus optional links to the track on Apple Music, Spotify, Deezer or MusicBrainz. Each call counts against the account's request quota, like a direct API call, and a retry counts again; on paid plans, requests beyond the plan's included allowance are billed at the plan's rate at the end of the billing period. Do not use for lyrics or to find several songs in a long recording.

recognize_song_from_url

Use this when the user asks which radio or live streams their account monitors with AudD stream recognition. Returns each stream's radio_id, its URL, and whether recognition is currently running. Read-only.

list_streams