sampaiodev.
PTEN
CPU transcription APIOpen-source

transcricao

A FastAPI API for audio/video upload, transcription with faster-whisper and Docker Compose deployment with Traefik labels.

FastAPIfaster-whisperCTranslate2DockerTraefik

Technical reading

Quick case read

Problem

Not every pipeline needs a large stack. On a simple VPS, the challenge is loading the model once, limiting file size, exposing healthcheck and keeping deployment predictable.

Solution

The API initializes the model on startup, receives files through `/transcribe`, defaults to `int8` on CPU and exposes `/health` with model, device and compute type.

Stack

FastAPI · faster-whisper · CTranslate2 · Docker

Status

Open-source

Architecture

Fewer services, direct path to transcription

Deliberately lean project: request comes in, local engine processes and the API responds. The focus is CPU-only and simple deploy.

Technical flow

  • Input
  • Processing
  • Storage
  • Output
Flowchart
Rendering flowchart…

Step-by-step flow

01Input
Audio/videoFile sent for transcription
02API
FastAPI/transcribe endpoint, upload and validation
03Runtime
Loaded modelModel initialized on startup
04Processing
faster-whisper/CTranslate2CPU-only/int8 transcription
05Output
JSON/transcriptionText and segments returned by the API
06Operations
Docker/Traefik/PortainerPackaging and deploy routing
Diagram source (Mermaid)
Paste into any Mermaid renderer
flowchart LR
  file["Audio/video"]
  api["FastAPI"]
  model["Loaded model"]
  engine["faster-whisper/CTranslate2"]
  json["JSON/transcription"]
  deploy["Docker/Traefik/Portainer"]
  file --> api
  api --> model
  model --> engine
  engine --> json
  json --> deploy
1. Audio/video (Input) → FastAPI. 2. FastAPI (API) → Loaded model. 3. Loaded model (Runtime) → faster-whisper/CTranslate2. 4. faster-whisper/CTranslate2 (Processing) → JSON/transcription. 5. JSON/transcription (Output) → Docker/Traefik/Portainer. 6. Docker/Traefik/Portainer (Operations).

Stack and responsibilities

  • FastAPI

    Receives upload, validates parameters and returns the transcription.

  • faster-whisper

    Local transcription engine.

  • CTranslate2

    Optimized CPU execution.

  • Docker Compose

    Local/Portainer deploy with environment variables.

  • Traefik

    Routing labels in Swarm/Portainer environments.

Technical decisions

  • CPU-first

    Default config uses CPU device and int8 compute type for simple VPSs.

  • Model loaded once

    Avoids startup cost on every request.

Operations

  • documentedHealthcheck

    `/health` returns status, model, device and compute type.

  • documentedEnvironment variables

    PORT, WHISPER_MODEL, language, file limit, CPU threads.

  • not publicPersistence

    README does not document a database; response is direct through the API.

Status and next steps

  • Add a queue if usage requires controlled concurrency.
  • Document production limits by file size/duration.

Contact

Want something similar for your process?

If there is repeated input, a manual step and an expected output, there is probably a system to design.

Talk about a project