VoiceVault

VoiceVault is an archival audio app where users upload recordings, get speech-to-text transcripts, and search their archive with RAG-ready chunks.

What The App Does

• User registration and login
• Upload audio/video recordings (private or public)
• Store original media in Supabase Storage bucket (archives)
• Transcribe media locally with faster-whisper
• Save transcript chunks to rag_chunks
• Save prompt/context metadata to archive_metadata
• View feed/history, open full post detail, play original audio
• Edit and delete your own posts
• Download a post as a ZIP bundle
• Search transcript chunks for RAG use

Tech Stack

• Backend: Flask (backend/main.py, backend/api_routes.py)
• Data + storage: Supabase Postgres + Supabase Storage (backend/db_queries.py)
• Frontend: React + Vite (frontend/)
• Transcription: faster-whisper (local inference)

Project Structure

• schema.sql: DB schema
• backend/main.py: Flask app entrypoint
• backend/api_routes.py: API routes and orchestration
• backend/db_queries.py: Supabase table/storage functions
• frontend/src/App.jsx: main app shell/navigation
• frontend/src/pages/: Feed, Create, History, Search, Post detail, Settings

Backend Environment

Create backend/.env:

SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
SUPABASE_BUCKET=archives

# Optional
BACKEND_UPLOAD_DIR=uploads
WHISPER_MODEL=base
WHISPER_DEVICE=cpu
WHISPER_COMPUTE_TYPE=int8
EMBEDDING_PROVIDER=local
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# OPENAI_API_KEY=...   # only needed if EMBEDDING_PROVIDER=openai

Notes:

• Use SUPABASE_SERVICE_ROLE_KEY, not publishable/anon key.
• Ensure bucket name matches exactly (archives).

How To Start

1. Setup database

1. Open Supabase SQL editor.
2. Run schema.sql.
3. Confirm tables and storage bucket are created.

2. Start backend

cd TitanForge/backend
pip install -r ../requirements.txt
python main.py

Backend runs at http://localhost:5000.

3. Start frontend

cd TitanForge/frontend
npm install
npm run dev

Frontend runs at http://localhost:5173 (default Vite).

How To Use The App

1. Register or log in from the landing screen.
2. Go to Make an Archive Post.
3. Fill title/description, choose visibility, upload an audio/video file.
4. Wait for transcription to finish.
5. Open My Feed or History to view the post.
6. Click View Post to:

• Play original audio
• Read full transcript
• See timestamped chunks
• Download ZIP archive

7. In History, use edit/delete actions for your own posts.
8. Use Search Archives to query transcript chunks.

Main API Endpoints

Auth:

• POST /api/auth/register
• POST /api/auth/login

Upload and processing:

• POST /api/posts/upload

Posts and history:

• GET /api/posts
• GET /api/posts/<post_id>
• PUT /api/posts/<post_id>/edit
• DELETE /api/posts/<post_id>?user_id=<id>
• GET /api/users/<user_id>/history

Playback and download:

• GET /api/posts/<post_id>/audio-url?user_id=<id>&expires_in=3600
• GET /api/posts/<post_id>/download

RAG:

• GET /api/posts/<post_id>/chunks
• GET /api/rag/search?user_id=<id>&q=<query>

Common Issues

• 403 / RLS during upload:
  • Usually wrong key type. Use service role key in backend .env.
• Audio not playing:
  • Verify archive_files.role='original_audio' exists for that post.
  • Verify bucket is archives.
  • Restart backend after .env changes.
• Whisper slow on CPU:
  • Use a smaller model or faster machine/GPU settings.