VoxArchive — Oral History Research Studio

A free, open-source desktop application for recording, transcribing, annotating, and analysing oral history interviews.

VoxArchive is built for researchers, archivists, and digital humanists who work with recorded testimonies. It runs fully offline — your data never leaves your machine.

---

Features

📚 Interview Library

• Import local audio and video files (MP4, MKV, MP3, WAV, FLAC, OPUS, …)
• Browse interviews from any PeerTube instance
• Cards show interviewee name, date, duration, language, and collection
• Filter and sort by collection, language, or date

▶ Player

• Embedded MPV player with frame-accurate seeking
• Conversation bubble view — interviewee on the right, interviewer on the left, coloured by speaker
• Active segment glows and auto-scrolls as the audio plays
• Click any bubble to jump to that moment
• Quick note bar — add a timestamped note without leaving the player
• Interactive mini-timeline showing all speakers across the full interview

📝 Transcribe

• Manual transcription workspace — pause audio and type, all in one screen
  • Space — play / pause without leaving the keyboard
  • Ctrl+T — insert timestamp + active speaker name at cursor
  • Ctrl+1 / Ctrl+2 / … — switch active speaker instantly
  • Click speaker tile to mark who is talking and insert their name
  • A-B loop — mark a section and repeat it while you type
  • Live word count + auto-save every 60 seconds
• Auto-transcription with Whisper — one click, streams segments live as they appear
  • Models: tiny / base / small / medium / large
  • Optional language hint
• Import / export: SRT, VTT, plain text

🗒 Notes

• Timestamped research notes linked to specific moments
• Six colour categories for annotation types
• Visual timeline strip at the bottom — coloured dots for every note across the interview
• Click any dot to jump to that note

🏷 Metadata

• Full interview metadata: interviewee, interviewer, date, location, language, collection
• Speaker profiles with roles
• Dublin Core fields for archival compatibility
• Tag management

🔍 Search

• Full-text search across transcripts, notes, and metadata simultaneously
• Results grouped by interview with bolded match context
• Click any result to open the interview at that exact moment

🎨 Thematic Coding

• Codebook with colour-coded research themes
• Select any transcript text → click a code → coloured highlight applied
• Code frequency bar chart
• Export coded segments as CSV

📤 Export

• PDF research report (transcript + highlights + notes)
• DOCX (Word)
• SRT / VTT subtitle files
• Plain text transcript
• JSON archive (full data dump)
• CSV (segments or highlights table)
• OHMS XML — Oral History Metadata Synchronizer format, compatible with Columbia University and major archives
• Citation generator — Chicago, APA 7th, MLA 9th, one-click copy

---

Installation

Linux (recommended)

# 1. Install system dependencies
sudo apt install python3 python3-pip mpv libmpv-dev ffmpeg   # Debian/Ubuntu
# or
sudo pacman -S python python-pip mpv ffmpeg                   # Arch

# 2. Clone the repository
git clone https://your-forgejo-instance/you/voxarchive.git
cd voxarchive

# 3. Install Python dependencies
pip install -r requirements.txt

# 4. Run
python3 main.py

Windows

Quick start: double-click setup_windows.bat — it handles everything automatically.

Manual steps if you prefer:

1. Install Python 3.10+ from python.org
   ⚠ During installation, tick "Add Python to PATH"

2. Install ffmpeg from ffmpeg.org
   Extract and add the bin/ folder to your system PATH

3. Open a terminal (Win+R → cmd) and run:

   pip install PyQt6 python-mpv requests openai-whisper reportlab python-docx feedparser mutagen
   

4. Download libmpv (the video engine):

   • Go to: https://sourceforge.net/projects/mpv-player-windows/files/libmpv/
   • Download the latest mpv-dev-x86_64-*.7z
   • Extract and copy mpv-2.dll into the voxarchive/ folder (same folder as main.py)

5. Launch:

   python main.py
   

   Or double-click launch_windows.bat

macOS

# 1. Install Homebrew if needed: https://brew.sh
brew install python mpv ffmpeg

# 2. Clone and install
git clone https://your-forgejo-instance/you/voxarchive.git
cd voxarchive
pip3 install -r requirements.txt

# 3. Run
python3 main.py

---

Optional dependencies

These are not required to run VoxArchive — missing packages are detected at startup with a helpful message.

Package	Purpose
openai-whisper	Automatic speech-to-text transcription
reportlab	PDF export
python-docx	Word (.docx) export
mutagen	Read audio metadata on import

---

Data storage

All data is stored locally in:

Platform	Path
Linux	~/.voxarchive/voxarchive.db
Windows	C:\Users\<you>\AppData\Local\VoxArchive\voxarchive.db
macOS	~/Library/Application Support/VoxArchive/voxarchive.db

No account, no cloud, no tracking.

---

Keyboard shortcuts

Global

Shortcut	Action
Alt+1 … Alt+8	Switch to panel (Library, Player, Transcribe…)
Ctrl+Shift+T	Switch to Transcribe panel
Ctrl+F	Open Search panel
Ctrl+K	Focus global search bar
Escape	Return to Library

In Transcribe

Shortcut	Action
F4	Play / pause (standard transcription shortcut)
F5	Play / pause (alternative)
Space	Types a normal space — not bound to playback
Ctrl+T	Insert [timestamp] ActiveSpeaker: at cursor
Ctrl+1 … Ctrl+8	Select speaker and insert their name + timestamp
Tab	Cycle to next speaker tile (no insertion)
Ctrl+← / Ctrl+→	Rewind / forward 5 seconds
Ctrl+[ / Ctrl+]	Rewind / forward 2 seconds (fine control)
Ctrl+0	Reset playback speed to 1×
Alt+A / Alt+B	Set A-B loop start / end at current position
Alt+C	Clear A-B loop
Ctrl+N	Focus quick note input
Ctrl+S	Save segments to database

---

Built with

• PyQt6 — UI framework
• python-mpv — video/audio playback via libmpv
• openai-whisper — automatic transcription
• SQLite — local database

---

License

MIT License — see LICENSE

---

Contributing

Issues, pull requests, and translations are welcome.
This project follows oral history community standards, including compatibility with OHMS and Dublin Core.