mannpatel/VoiceVault
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
Gaumit Kauts
2026-02-15 11:55:06 -07:00
parent 6e987e7d4f
commit d5f9f26643
1 changed files with 95 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
README.md
View File

@@ -1,84 +1,130 @@
# VoiceVault # VoiceVault
Schema-driven archival audio backend + frontend. VoiceVault is an archival audio app where users upload recordings, get speech-to-text transcripts, and search their archive with RAG-ready chunks.
## What It Does ## What The App Does
- Register / login users - User registration and login
- Upload original audio/video to Supabase Storage bucket (`archives`) - Upload audio/video recordings (private or public)
- Create `audio_posts` records in Postgres - Store original media in Supabase Storage bucket (`archives`)
- Transcribe media locally with `faster-whisper` - Transcribe media locally with `faster-whisper`
- Save transcript chunks to `rag_chunks` (with embeddings) - Save transcript chunks to `rag_chunks`
- Build prompt context and store in `archive_metadata` - Save prompt/context metadata to `archive_metadata`
- Search user chunks with RAG endpoint (vector mode or text fallback) - 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 ## Project Structure
- `backend/main.py` Flask app entry - `schema.sql`: DB schema
- `backend/api_routes.py` API routes and upload/transcription flow - `backend/main.py`: Flask app entrypoint
- `backend/db_queries.py` Supabase DB/storage helpers - `backend/api_routes.py`: API routes and orchestration
- `schema.sql` database schema - `backend/db_queries.py`: Supabase table/storage functions
- `frontend/` React app - `frontend/src/App.jsx`: main app shell/navigation
- `frontend/src/pages/`: Feed, Create, History, Search, Post detail, Settings
## Environment (`backend/.env`) ## Backend Environment
Required: Create `backend/.env`:
- `SUPABASE_URL`
- `SUPABASE_SERVICE_ROLE_KEY` (service role key, not publishable key)
- `SUPABASE_BUCKET=archives`
Optional: ```env
- `BACKEND_UPLOAD_DIR=uploads` SUPABASE_URL=your_supabase_url
- `WHISPER_MODEL=base` SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
- `WHISPER_DEVICE=cpu` SUPABASE_BUCKET=archives
- `WHISPER_COMPUTE_TYPE=int8`
## Run Backend # Optional
BACKEND_UPLOAD_DIR=uploads
WHISPER_MODEL=base
WHISPER_DEVICE=cpu
WHISPER_COMPUTE_TYPE=int8
```
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
```bash ```bash
cd backend cd TitanForge/backend
pip install -r ../requirements.txt
python main.py python main.py
``` ```
Backend runs on `http://localhost:5000`. Backend runs at `http://localhost:5000`.
## Run Frontend ### 3. Start frontend
```bash ```bash
cd frontend cd TitanForge/frontend
npm install npm install
npm run dev npm run dev
``` ```
Set frontend API base to `http://127.0.0.1:5000/api` (or your backend host). Frontend runs at `http://localhost:5173` (default Vite).
## Core API Endpoints ## 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: Auth:
- `POST /api/auth/register` - `POST /api/auth/register`
- `POST /api/auth/login` - `POST /api/auth/login`
Upload + processing: Upload and processing:
- `POST /api/posts/upload` (multipart form-data: `file`, `user_id`, `title`, `visibility`, optional metadata) - `POST /api/posts/upload`
History + RAG: Posts and history:
- `GET /api/users/<user_id>/history`
- `GET /api/rag/search?user_id=<id>&q=<text>`
- `GET /api/rag/search?user_id=<id>&query_embedding=[...]`
Playback:
- `GET /api/posts/<post_id>/audio-url?user_id=<id>` (required for private posts)
- `GET /api/posts/<post_id>/archive.zip?user_id=<id>` (download archive package; required for private posts)
Post data:
- `GET /api/posts` - `GET /api/posts`
- `GET /api/posts/<post_id>` - `GET /api/posts/<post_id>`
- `GET /api/posts/<post_id>/bundle` - `PUT /api/posts/<post_id>/edit`
- `GET /api/posts/<post_id>/files` - `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/posts/<post_id>/chunks`
- `GET /api/rag/search?user_id=<id>&q=<query>`
## Notes ## Common Issues
- Original media is stored in Supabase Storage; DB stores the object path in `archive_files` (`role=original_audio`). - `403 / RLS` during upload:
- Transcript text/chunks/metadata/audit remain in Postgres tables. - Usually wrong key type. Use service role key in backend `.env`.
- If storage upload fails with RLS errors, verify service-role key and bucket policies. - 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.