{"id":15136454,"url":"https://github.com/datarabbit-ai/transcription_service","last_synced_at":"2026-02-14T02:03:20.936Z","repository":{"id":253338791,"uuid":"843186864","full_name":"datarabbit-ai/transcription_service","owner":"datarabbit-ai","description":"System/service with REST API for extracting text transcriptions from movies and audio recordings in most popular video formats.","archived":false,"fork":false,"pushed_at":"2025-03-17T17:03:18.000Z","size":275,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-06T16:40:05.028Z","etag":null,"topics":["containers","datarabbit","rest-api","speech-to-text","stt","transcription","transcription-services","whisper"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/datarabbit-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-16T01:01:02.000Z","updated_at":"2024-08-16T15:56:17.000Z","dependencies_parsed_at":"2024-12-17T18:21:41.879Z","dependency_job_id":"33a7dcce-3faf-4485-8871-dbf1765f86df","html_url":"https://github.com/datarabbit-ai/transcription_service","commit_stats":{"total_commits":30,"total_committers":1,"mean_commits":30.0,"dds":0.0,"last_synced_commit":"889e842921605090177d54028b6800a6500e76c2"},"previous_names":["datarabbit-ai/transcription_service"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/datarabbit-ai/transcription_service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datarabbit-ai%2Ftranscription_service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datarabbit-ai%2Ftranscription_service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datarabbit-ai%2Ftranscription_service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datarabbit-ai%2Ftranscription_service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datarabbit-ai","download_url":"https://codeload.github.com/datarabbit-ai/transcription_service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datarabbit-ai%2Ftranscription_service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29431593,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-13T22:20:51.549Z","status":"online","status_checked_at":"2026-02-14T02:00:07.626Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["containers","datarabbit","rest-api","speech-to-text","stt","transcription","transcription-services","whisper"],"created_at":"2024-09-26T06:21:54.346Z","updated_at":"2026-02-14T02:03:20.907Z","avatar_url":"https://github.com/datarabbit-ai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Transcription service\nThis project extracts text transcriptions from movies and audio recordings in most popular video formats.\n\n\n## Capabilities\n\n- Supports transcription of both popular video and audio formats\n- Should be able to handle long videos (up to several hours)\n- Scalable architecture using Redis (with the extension of Redis Queue) for job queuing and worker management\n- Self-hosted solution using open-source Whisper AI model\n- RESTful API for file upload and transcription status checking\n- Separate worker processes for handling transcription tasks\n- Everything is containerized using Docker and Docker Compose, including cuda support setup\n- Option to include word timestamps in transcriptions\n\n## Architecture\nThe service consists of the following components:\n- API Server: Handles incoming requests and manages the transcription queue.\n- Redis: Acts as a message broker and job queue.\n- Worker: Processes transcription jobs using the Whisper AI model.\n\n![architecture.png](resources/architecture.png)\n\n## Running the containerized service\n### Prerequisites\n\n- Docker and Docker Compose\n- NVIDIA GPU with CUDA support (optional, for GPU acceleration)\n- NVIDIA drivers and NVIDIA Container Runtime installed on the host system (optional, for GPU acceleration)\n\n### Installation and setup (containerized)\n\n1. Clone this repository:\n   ```bash\n   git clone \u003corg_path\u003e/transcription_service.git\n   cd transcription_service\n2. The environment variables are already set in the docker-compose.yml file. If you need to modify any settings, you can do so directly in the compose file or by creating a .env file in the project root directory.\n3. Build and start the services using Docker Compose:\n    ```bash\n    docker-compose up --build\n    ```\n\n### Configuration\nConfiguration of different service components can be found in Docker Compose file under `docker/docker-compose.yml`.\n\n#### Environment variables\nThe following environment variables are configured in the docker-compose.yml file:\n\n- **REDIS_HOST**: Hostname of the Redis server (set to redis unless one wants to use a different/external Redis server)\n- **REDIS_PORT**: Port of the Redis server (set to 6379)\n- **REDIS_DB**: Number of Redis database used for tasks/jobs orchestration (defaults to 10)\n- **UPLOADS_DIR:** Directory for uploaded files (defaults to /app/uploads, and the directory can be accessed from the volume)\n- **TRANSCRIPTIONS_DIR**: Directory for storing transcriptions (set to /app/transcriptions, and the directory can be accessed from the volume)\n- **WHISPER_MODEL_NAME**: Whisper model to use (defaults to large-v3 with best quality, see alternative models in resource-scare scenarios)\n- **WHISPER_MODEL_DEVICE**: Device to run the model on (set to cuda for GPU acceleration)\n\n#### GPU support\nGPU support is enabled by default in the Docker Compose configuration. To use it:\n\n1. Ensure your host system has NVIDIA drivers and NVIDIA Container Runtime installed.\n2. The docker-compose.yml file already includes the necessary configuration:\n```yaml\ndeploy:\n  resources:\n    reservations:\n      devices:\n        - driver: nvidia\n          count: all\n          capabilities: [ gpu ]\nruntime: nvidia \n```\n\n#### Scaling workers\nTo scale the number of worker processes horizontally:\n\n1. Use Docker Compose's --scale option:\n```bash\ndocker-compose up --scale worker=3\n```\nThis command will start 3 worker containers, you can use whatever number you see fit.\n\n2. Alternatively, you can modify the docker-compose.yml file to include a deploy section for the worker service:\n```yaml\nworker:\n  # ... other configurations ...\n  deploy:\n    replicas: 3\n```\nThen run docker-compose up --build to apply the changes.\n\n**IMPORTANT**: Make sure to adjust the number of workers based on the available resources on your host system – especially when using GPU acceleration.\n\n#### Whisper Model Configuration\nBy default, the service uses the large-v3 Whisper model, which requires approximately 10-11GB of GPU memory (VRAM). \nYou can choose different models based on your hardware capabilities – with smaller options such as `tiny` or `base`\nrequiring much less resources and working very fast even on just CPUs – but providing lower transcription quality.\n\nFor a full list of available models and their capabilities, visit: https://github.com/openai/whisper?tab=readme-ov-file#available-models-and-languages\nTo change the model, update the WHISPER_MODEL_NAME environment variable in the docker-compose.yml file under the worker service.\n**Note: Models are not embedded in the worker images and are downloaded at runtime.**\n\n## Running the service locally/development setup\n\nFor local development follow the steps below:\n1. Clone this repository:\n   ```bash\n   git clone \u003corg_path\u003e/transcription_service.git\n   cd transcription_service\n2. Create a virtual environment and install dependencies (poetry must be installed in the system already):\n   ```bash\n   poetry install\n   ```\n3. Set up pre-commit hooks (pre-commit must be installed in the system already):\n   ```bash\n   pre-commit install\n   ```\n4. Start the service using Uvicorn:\n   ```bash\n   uvicorn transcription_service.main:app --reload --env-file=.example.env\n   ```\n\nWorkers should be able to be started with a similar fashion, using the following command:\n```bash\npython -m transcription_service.worker\n```\n\nRedis server should be running on the default port (6379) on localhost.\n\n## Testing and usage\n\nTo run the end-to-end transcription workflow, you can use the provided utility script:\n```bash\npython scripts/end_to_end_transcription.py\n```\nThis script uploads a sample video file to the service, checks the transcription status, \nand downloads the transcription once it's ready.\n\nNote: ensure the service is running before executing the script + you're running it from virtual environment with\nall dependencies installed.\n\n### Call with example arguments\n```bash\npython scripts/end_to_end_transcription.py localhost:8001 https://www.youtube.com/watch?v=TX4s0X6FDcQ /path/to/local/sandbox/outputs/TX4s0X6FDcQ_transcription.txt --include-word-timestamps\n```\nThe call above will upload the video to the service running at localhost:8001 from the provided YouTube link (we \nsupport both paths to local files, and YT links for convenience, as it was a popular internal use case), check\nthe transcription status, and download the transcription once it's ready to path specified. \nThe `--include-word-timestamps` flag is responsible for setting the generated transcription to \"rich\" format\nwhich will include word timestamps in the transcription.\n\n### Swagger API documentation\nAll endpoints are documented using Swagger UI, which can be accessed at http://localhost:8001/docs.\n\n## TODOs\nFuture (possible) improvements:\n- Add configurable file size restrictions for uploads and video lengths to manage system resources effectively.\n- Implement user authentication and authorization for secure access to the API.\n- Add support for other TTS models than Whisper (it was prioritized due to being SOTA).\n\n## License\n\nExtracted from a larger system, this component was brought to you by 🐰 [datarabbit.ai](https://www.datarabbit.ai/) 🐰\n\nIt is licenced under the Apache License, Version 2.0. in order to allow for the flexibility of use and modification.\n\nDo something cool with it! 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatarabbit-ai%2Ftranscription_service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatarabbit-ai%2Ftranscription_service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatarabbit-ai%2Ftranscription_service/lists"}