Controlling enterprise endpoint cost

The enterprise endpoint (POST https://enterprise.audd.io/) recognizes music in long audio and video — full songs, DJ sets, podcasts, broadcasts, uploaded videos. Unlike the standard endpoint, which handles one short clip per call, the enterprise endpoint chunks a file server-side and bills for the audio it processes. This page explains the billing unit and the four request parameters that let you decide how much of a file actually gets metered: limit, every, skip, and skip_first_seconds.

TL;DR

The enterprise endpoint bills per 12 seconds of audio processed, not per API call and not per match.
limit=N is a hard ceiling on how many 12-second chunks the server will recognize. Always set it in development. It is the single most important guard against an accidental hours-long bill.
every / skip sample the file — recognize a run of chunks, then skip a run — when you don’t need wall-to-wall coverage.
skip_first_seconds drops a known intro before metering starts.
The decision rule: the smaller the slice of audio you actually need to recognize, the less you pay. A “does this contain any music at all” check is the cheapest thing you can run; a complete, gap-free tracklist of a long file is the most expensive.

Why this matters

The standard endpoint has a natural cost ceiling: one short clip, one call. The enterprise endpoint does not. You can hand it a one-hour mix or a multi-hour broadcast capture, and by default it will work through the entire file in 12-second chunks. Each chunk that gets recognized is metered. A long file processed end-to-end is therefore many times more expensive than a short one, and the cost scales with duration — not with how many distinct songs the file happens to contain.

That makes cost a design decision you make per workload, not a fixed price you look up once. A copyright “is there any music here” gate, a DJ-set tracklist, and a broadcast compliance log are three different shapes of the same endpoint, and each wants a different combination of the four parameters below. Getting that combination right is the difference between paying for the audio you needed and paying for audio you threw away.

Always set limit during development. The enterprise endpoint bills per 12 seconds of audio processed. An unbounded call on a multi-hour file can ingest hours of audio and produce hundreds of metered chunks before it returns. Start with a small limit (for example limit=10) and raise it only once you understand the cost on your real inputs.

The billing unit: 12-second chunks

When you upload a file, the server treats it as a sequence of 12-second chunks. Recognition runs chunk by chunk, and each chunk the server recognizes counts as one billable unit. A 60-second file is five chunks; a one-hour file is 300 chunks; a 12-minute file is 60 chunks.

Two consequences follow directly:

Duration drives cost, not song count. A one-hour file of silence and a one-hour DJ set cost the same to scan end-to-end, because both are 300 chunks. The number of matches you get back does not change the bill.
A match can span multiple chunks. The same track playing for two minutes appears across many consecutive chunks, each metered. You’ll see this in a real response as the same artist/title repeating with an increasing offset. That repetition is normal and is exactly what every exists to thin out when you don’t need every occurrence.

The dollar figure attached to a chunk depends on your plan and is shown on the dashboard. This page deals only with the unit (the 12-second chunk) and how the parameters change how many units you pay for — the relative effect, which is the same on every plan.

`limit` — stop after N chunks

limit is the upper bound on the number of chunks the server will recognize before it stops and returns what it has. It is a hard ceiling, independent of how long the file is.

limit does two jobs:

It caps cost on a per-call basis. Whatever you pass as a file, the bill for that call cannot exceed limit chunks. This is why it’s mandatory in development: a wrong URL, a surprise multi-hour file, or a loop that resubmits cannot run away.
It’s enough on its own for “is there any music” questions. If all you need is a yes/no, limit=1 recognizes a single chunk and returns. That is the cheapest possible enterprise call.

from audd import AudD

audd = AudD("your-api-token")

# Cheapest possible check: does the first chunk contain recognizable music?
matches = audd.recognize_enterprise(
    "https://audd.tech/djatwork_example.mp3",
    limit=1,
)
print("music detected" if matches else "nothing recognized in first chunk")

limit does not change which part of the file is scanned — recognition still starts at the beginning (after any skip_first_seconds) and works forward. It only decides when to stop. To check a different part of the file, combine limit with skip_first_seconds (below).

`every` and `skip` — sampling instead of full coverage

every and skip describe a repeating pattern over the chunk sequence:

every — how many chunks to recognize in a row.
skip — how many chunks to skip after each recognized run.

The server recognizes every chunks, skips skip chunks, recognizes every again, and so on across the file. Only the recognized chunks are metered. The skipped chunks cost nothing.

A few concrete patterns:

Goal	`every`	`skip`	Effect
Recognize every chunk (default, full coverage)	1	0	All chunks metered
One 12-second probe per minute	1	4	Recognize 12 s, skip 48 s — ~1/5 the audio metered
One 12-second probe per two minutes	1	9	Recognize 12 s, skip 108 s — ~1/10 the audio metered
Two chunks then a gap	2	8	Recognize 24 s, skip 96 s

The trade is coverage against cost. Sampling assumes that whatever you’re looking for plays continuously enough to land in one of your probes. That’s a safe assumption for “is a song playing under this whole video” and a bad one for “catch every short jingle.” A 6-second stinger between skip runs can fall entirely in a skipped gap and never be recognized.

Sampling can miss short or intermittent audio. every/skip is built for sustained use — a track playing for minutes, background music under a video. If you need to catch brief or scattered cues, recognize every chunk (every=1, skip=0) and control cost with limit instead.

`skip_first_seconds` — drop a known intro

skip_first_seconds tells the server how many seconds at the start of the file to skip before recognition begins. The skipped seconds aren’t recognized and aren’t metered.

Use it when you know the front of the file isn’t worth scanning: a fixed show intro, a sponsor read, a countdown, leader silence on a broadcast capture. Skipping a 90-second intro on every file in a large batch removes those chunks from every bill.

# Skip a 90-second intro, then recognize at most 20 chunks of the real content
matches = audd.recognize_enterprise(
    "https://audd.tech/djatwork_example.mp3",
    skip_first_seconds=90,
    limit=20,
)

Two notes:

skip_first_seconds shifts where recognition starts. It does not sample — use every/skip for that.
Do not combine skip_first_seconds with use_timecode. use_timecode asks the server to take the start time from a t, time_continue, or start parameter in the URL instead; the two settings configure the same thing two different ways.

Putting the parameters together

The four parameters compose. Recognition begins after skip_first_seconds, proceeds in the every/skip pattern, and halts when it has recognized limit chunks (or reaches the end of the file). A practical way to think about the order:

skip_first_seconds — where do I start?
every / skip — how densely do I sample from there?
limit — what’s the hard ceiling, no matter what?

You can use limit alone (full coverage up to a cap), sampling alone (thin coverage of the whole file), or both (thin coverage of the whole file and a ceiling). For development, keep limit set in all three cases.

Worked example: a one-hour file, three ways

Take the hour-long DJ mix at https://audd.tech/djatwork_example.mp3. End to end, one hour is 300 twelve-second chunks. Here’s how the same file meters under three different intents.

1. “Does this contain any music?” — cheapest.

matches = audd.recognize_enterprise(
    "https://audd.tech/djatwork_example.mp3",
    limit=1,
)

One chunk recognized. One billable unit, regardless of the file being an hour long. This is the right call for a fast gate: route the upload to a fuller scan only if this first probe finds something.

2. “Roughly what’s in here?” — sampled, ~1/5 the cost.

matches = audd.recognize_enterprise(
    "https://audd.tech/djatwork_example.mp3",
    every=1,
    skip=4,        # recognize 12 s, skip 48 s
    limit=60,      # ceiling, in case the file is longer than expected
)

every=1, skip=4 recognizes one chunk per minute: about 60 chunks across the hour instead of 300 — roughly one-fifth the metered audio. You get a representative tracklist of what played for a while, and you’ll miss anything that only played inside the skipped 48-second gaps. The limit=60 is a backstop, not the expected stopping point here.

3. “Give me the complete, gap-free tracklist.” — most expensive.

matches = audd.recognize_enterprise(
    "https://audd.tech/djatwork_example.mp3",
    every=1,
    skip=0,        # recognize every chunk
    limit=300,     # the whole hour
)

Every chunk recognized: up to 300 billable units for the hour. This is the shape you use when the tracklist is the deliverable — DJ-set credits, a broadcast compliance log, copyright evidence — and missing a 12-second segment is not acceptable. It costs roughly five times option 2 and 300 times option 1, for the same input file.

Which is correct depends on intent: the intent picks the parameters, and the parameters pick the cost — decide that on purpose rather than discover it on an invoice.

Common mistakes

No limit in development. A typo’d URL or an unexpectedly long file meters every chunk to the end before returning. Always set a small limit while building; raise it deliberately. This is the one rule with no exceptions.
Full coverage when sampling would do. Running every=1, skip=0 for a “yes/no music?” question pays for the whole file to answer a one-chunk question. Use limit=1, or sample.
Sampling when full coverage is required. Using every/skip for a copyright log or a tracklist that has to be complete will silently drop whatever fell in the gaps. If completeness is the requirement, recognize every chunk and bound cost with limit.
Re-scanning to re-run a policy. Recognition re-bills every time. Store the match list keyed by file ID and re-run your decision logic against the stored results instead of calling the endpoint again.
Assuming song count drives cost. It doesn’t — duration and your sampling settings do. A silent hour and a packed hour cost the same to scan fully.
Mixing skip_first_seconds and use_timecode. They set the same start point two ways. Pick one.

Related