How brvieira/whatsapp-transcriber works
WhatsApp Transcriber turns an exported chat ZIP into a searchable, readable conversation with original media and audio transcripts. The main path is upload, background extraction and parsing, per-audio transcription, finalization, then conversation viewing with live progress. The README documents the service-level workflow and major UI features; sampled source confirms key API, ingest, parser, and audio-pipeline responsibilities. Some UI and worker implementation details were not sampled, so those links rely on README documentation rather than inspected calls.
Main entry points: ingest.ts ZIP ingestion · schema.ts MongoDB · api.ts API client · conversations.ts Conversation routes
Components 32
Web interface
- ZIP upload
apps/web/components/UploadArea.tsx - Conversation pages
apps/web/components/ConversationView.tsx - Chat display
apps/web/components/chat/ChatView.tsx - Participant panel
apps/web/components/chat/ParticipantsPanel.tsx - Live progress
apps/web/hooks/useConversationEvents.ts - Message loading
apps/web/hooks/useMessages.ts - API client
apps/web/lib/api.ts
API
- HTTP routes
apps/api/src/app.ts - Conversation routes
apps/api/src/routes/conversations.ts - Event stream
apps/api/src/routes/events.ts - Message routes
apps/api/src/routes/messages.ts - Media routes
apps/api/src/routes/media.ts - API serializers
apps/api/src/serializers.ts
Background processing
- ZIP ingestion
apps/worker/src/ingest.ts - Safe extraction
apps/worker/src/zip/safeExtract.ts - Conversation state
apps/worker/src/conversation.ts - Finalization
apps/worker/src/finalize.ts - Audio jobs
apps/worker/src/transcribe.ts - Audio pipeline
apps/worker/src/transcription/pipeline.ts - Audio conversion
apps/worker/src/audio/ffmpeg.ts - Media hashing
apps/worker/src/media/hash.ts
Chat and transcription
- Chat parser
packages/core/src/parser/index.ts - Attachment parsing
packages/core/src/parser/attachments.ts - Date parsing
packages/core/src/parser/dates.ts - Format detection
packages/core/src/parser/patterns.ts - Provider interface
apps/worker/src/transcription/provider.ts - OpenAI transcription
apps/worker/src/transcription/openai.ts - Mock transcription
apps/worker/src/transcription/mock.ts
Storage and queue
- MongoDB
packages/db/src/schema.ts - Redis job queue
packages/queue/src/index.ts - Local media files
Other components
- Uploader
Connections 38
- Uploader → ZIP upload: uploads ZIP
- ZIP upload → API client: sends upload
- API client → Conversation routes: calls API
- Conversation routes → Redis job queue: enqueues ingest
- Conversation routes → MongoDB: stores upload state
apps/api/src/routes/conversations.ts - Conversation routes → Local media files: writes ZIP
apps/api/src/routes/conversations.ts - Redis job queue → ZIP ingestion: dispatches job
- ZIP ingestion → Safe extraction: extracts archive
apps/worker/src/ingest.ts - ZIP ingestion → Chat parser: parses chat
apps/worker/src/ingest.ts - Chat parser → Attachment parsing: classifies media
packages/core/src/parser/index.ts - Chat parser → Date parsing: interprets dates
packages/core/src/parser/index.ts - Chat parser → Format detection: detects formats
packages/core/src/parser/index.ts - ZIP ingestion → MongoDB: writes messages
apps/worker/src/ingest.ts - ZIP ingestion → Local media files: stores extracted media
- ZIP ingestion → Conversation state: updates status
apps/worker/src/ingest.ts - ZIP ingestion → Redis job queue: schedules audio jobs
apps/worker/src/ingest.ts - Audio jobs → Audio pipeline: processes audio
- Audio pipeline → Audio conversion: converts and splits
apps/worker/src/transcription/pipeline.ts - Audio pipeline → Provider interface: requests transcription
apps/worker/src/transcription/pipeline.ts - Provider interface → OpenAI transcription: uses provider
- Provider interface → Mock transcription: uses provider
- Audio jobs → MongoDB: stores transcripts
- ZIP ingestion → Media hashing: hashes media
apps/worker/src/ingest.ts - Finalization → MongoDB: saves final stats
- Redis job queue → Finalization: dispatches after audio
- API client → Event stream: opens SSE
- Event stream → MongoDB: watches progress
apps/api/src/routes/events.ts - Event stream → Live progress: streams updates
- API client → Message routes: requests messages
- Message routes → MongoDB: reads messages
apps/api/src/routes/messages.ts - Message routes → API serializers: formats responses
apps/api/src/routes/messages.ts - Conversation routes → API serializers: formats summaries
apps/api/src/routes/conversations.ts - API client → Media routes: requests media
- Media routes → Local media files: serves media
- Conversation pages → Message loading: loads conversation
- Conversation pages → Live progress: shows progress
- Conversation pages → Chat display: renders chat
- Chat display → Participant panel: shows participants