audio_helper.api module

Audio Helper — FastAPI HTTP surface.

Exposes every public function in audio_helper.main as an HTTP endpoint so audio-helper can be dropped behind any reverse proxy and consumed by other services. Kept intentionally minimal:

  • Multipart uploads for audio inputs (UploadFile), streamed straight to a temporary file so large clips don’t blow up memory.

  • FileResponse for single-file outputs (/convert, /chunk …).

  • ZIP-encoded StreamingResponse for multi-file outputs (/split, /separate) so the client gets one download per call.

  • BackgroundTasks cleans temp files after the response has been streamed — no leftover garbage on disk after a request.

Install the extra to get the runtime dependencies:

pip install 'audio-helper[api]'

Then run the app with any ASGI server:

uvicorn audio_helper.api:app --host 0.0.0.0 --port 8000

A minimal single-page GUI (“audition bench”) is served at GET /gui (and GET / redirects there): drop an audio file, pick an operation, run it against these same endpoints, then A/B the input vs output in <audio> players and download the result.

Usage Example

>>> # Start the server:
>>> #   uvicorn audio_helper.api:app --reload
>>> # Convert a file:
>>> #   curl -F 'file=@in.mp3' -F 'freq=22050' -F 'channels=1' \
>>> #        -o out.wav http://localhost:8000/convert
>>> # Get a file's duration (JSON):
>>> #   curl -F 'file=@in.mp3' http://localhost:8000/duration
>>> # Full OpenAPI docs at http://localhost:8000/docs

Author

Warith Harchaoui, Ph.D. — https://linkedin.com/in/warith-harchaoui/

audio_helper.api.chunk(background, file=fastapi.File, start=fastapi.Form, end=fastapi.Form, output_format=fastapi.Form)

Extract a [start, end] slice from the uploaded audio.

Parameters:

  • background (fastapi.BackgroundTasks)

  • file (fastapi.UploadFile)

  • start (float)

  • end (float)

  • output_format (str)

Return type:

fastapi.responses.FileResponse

audio_helper.api.concat(background, files=fastapi.File, output_format=fastapi.Form)

Concatenate multiple uploaded audio files head-to-tail.

Parameters:

  • background (fastapi.BackgroundTasks)

  • files (list[fastapi.UploadFile])

  • output_format (str)

Return type:

fastapi.responses.FileResponse

audio_helper.api.convert(background, file=fastapi.File, output_format=fastapi.Form, freq=fastapi.Form, channels=fastapi.Form, encoding=fastapi.Form)

Re-encode an uploaded file at the requested sample rate / channels / codec.

Parameters:

  • background (fastapi.BackgroundTasks)

  • file (fastapi.UploadFile)

  • output_format (str)

  • freq (int)

  • channels (int)

  • encoding (str)

Return type:

fastapi.responses.FileResponse

audio_helper.api.duration(file=fastapi.File, background=None)

Return the duration in seconds of the uploaded audio file.

Parameters:

  • file (fastapi.UploadFile)

  • background (fastapi.BackgroundTasks)

Return type:

fastapi.responses.JSONResponse

audio_helper.api.gui()

Serve the self-contained single-page ‘audition bench’ GUI.

The page (defined in audio_helper.gui) is a build-step-free HTML + Tailwind-CDN + vanilla-JS client that calls the very same /convert / /chunk / … endpoints defined below. It adds no server-side logic — it is purely a friendlier front door to the API.

Returns:

The complete HTML document (status 200, text/html).

Return type:

HTMLResponse

audio_helper.api.health()

Simple liveness probe — no dependency check, just proves the app is up.

Return type:

dict

audio_helper.api.resemblance(a=fastapi.File, b=fastapi.File)

MFCC-based similarity score in [0, 1] between two uploaded audio files.

Parameters:

  • a (fastapi.UploadFile)

  • b (fastapi.UploadFile)

Return type:

fastapi.responses.JSONResponse

audio_helper.api.roomtone(background, file=fastapi.File, db=fastapi.Form, color=fastapi.Form, sample_rate=fastapi.Form, output_format=fastapi.Form)

Mix low-level colored ambient noise on top of an uploaded speech track.

Parameters:

  • background (fastapi.BackgroundTasks)

  • file (fastapi.UploadFile)

  • db (float)

  • color (str)

  • sample_rate (int)

  • output_format (str)

Return type:

fastapi.responses.FileResponse

audio_helper.api.root()

Redirect the bare root to the GUI so opening the server just works.

Return type:

fastapi.responses.RedirectResponse

audio_helper.api.separate(background, file=fastapi.File, device=fastapi.Form, workers=fastapi.Form, output_format=fastapi.Form)

Run Demucs source separation; response is a ZIP with the 4 stems.

Parameters:

  • background (fastapi.BackgroundTasks)

  • file (fastapi.UploadFile)

  • device (str | None)

  • workers (int)

  • output_format (str)

Return type:

fastapi.responses.StreamingResponse

audio_helper.api.silence(background, duration_seconds=fastapi.Form, sample_rate=fastapi.Form, output_format=fastapi.Form)

Generate a silent audio file of a given duration.

Parameters:

  • background (fastapi.BackgroundTasks)

  • duration_seconds (float)

  • sample_rate (int)

  • output_format (str)

Return type:

fastapi.responses.FileResponse

audio_helper.api.split(background, file=fastapi.File, seconds=fastapi.Form, output_format=fastapi.Form, suffix=fastapi.Form)

Split the uploaded audio into fixed-duration chunks; response is a ZIP.

Parameters:

  • background (fastapi.BackgroundTasks)

  • file (fastapi.UploadFile)

  • seconds (float)

  • output_format (str)

  • suffix (str)

Return type:

fastapi.responses.StreamingResponse