How thanhphamtmu/django-vosk-autotranscriber works
Project type and purpose
• This is a full-stack web application and REST API built with Django 4.x, Django REST Framework, and Django Channels.
• Its purpose is to accept user-uploaded audio files, transcode/process them via FFMPEG and VOSK (Vietnamese speech recognition), store the transcripts in a database, and present the results through a web UI, a JWT-secured API, and realtime WebSocket updates.
File structure
• Top-level “manage.py”, “requirements.txt”, “myproject” folder (Django settings/URLs/ASGI/WGSI).
• App folder “speech” contains views, serializers, models, forms, admin, routing, consumers, templates, utils (vosk_utils).
• “media/uploads” holds uploaded audio.
• Configuration files: settings.py includes DRF, Channels, JWT, and media settings.
• No explicit task queue—processing likely triggered synchronously in views or consumers.
Key insights from README
• Core modules: vosk_utils.py (speech recognition logic), views.py (upload/list/export endpoints), consumers.py (WebSocket real-time updates), serializers.py (REST API), routing.py (WS routing).
• External dependencies: VOSK models folder, FFMPEG binary, ReportLab for PDF export.
• JWT-protected API endpoints at /api/audio/. Web UI at /upload/, /list/, /export.
Main components
a. Clients
• Web browser (UI)
• Third-party consumer (REST API client)
• WebSocket client (within UI or standalone)
b. Application server
• Django HTTP server (Django views & DRF views)
• Django Channels ASGI server (WebSocket consumer)
c. Business logic modules
• File upload & form handling (forms.py / views.py)
• Audio conversion/transcoding (FFMPEG invoked in vosk_utils)
• Speech recognition engine (VOSK via vosk_utils.py)
• Export generator (ReportLab for PDF, plain text)
d. Data layer
• Relational database (models.py, migrations)
• File storage (media/uploads directory)
e. Integration points / external services
• Local FFMPEG binary
• VOSK model files
• JWT Auth provider (SimpleJWT library)
Relationships and data flow
1. User/browser sends HTTP POST to Django HTTP server →
• Django form or DRF serializer validates/stores uploaded file to media/uploads →
• Django calls vosk_utils: FFMPEG transcodes → VOSK processes audio → transcript returned.
2. Transcript + metadata saved in DB.
3. Server sends realtime update on WebSocket channel group “audio” via Django Channels consumer → Browser receives update.
4. User/browser or third-party GETs transcripts via REST API (/api/audio/) using JWT token.
5. For export, client hits /export/txt/ or /export/pdf/, Django view generates file via ReportLab or text writer, returns download.
Architectural patterns and principles
• Layered architecture: presentation (views/consumers), business logic (vosk_utils), data access (models), external integration (FFMPEG, VOSK).
• Separation of concerns: distinct modules for HTTP vs. WebSocket, forms vs. serializers, synchronous processing vs. realtime notification.
• Stateless API with JWT authentication.
• Shared media directory for persistence of audio.
Final checklist
• [ ] All main components present and labeled
• [ ] Architectural boundary grouping (e.g., “App Server”)
• [ ] Notes on JWT authentication path for API
• [ ] Realtime WebSocket update flow clearly illustrated
• [ ] External dependencies (FFMPEG, VOSK models) shown outside core app