Bristlenose takes a folder of interview recordings and produces organised research findings — quotes grouped by screen and theme, sentiment flagged, friction surfaced. This page covers everything from installation to daily use.
Download Bristlenose.dmg from GitHub Releases, drag to Applications, open it. The app bundles Python, FFmpeg, and Whisper — no terminal needed.
First launch: macOS will block it. Go to System Settings → Privacy & Security, scroll down, click "Open Anyway". One time only. Requires macOS 15 Sequoia, Apple Silicon (M1+).
brew install cassiocassio/bristlenose/bristlenoseHandles Python, FFmpeg, and all dependencies.
python -m pip install --user pipx then python -m pipx ensurepathwinget install FFmpegpipx install bristlenosesudo apt install ffmpeg (Ubuntu/Debian) or sudo dnf install ffmpeg-free (Fedora)pipx install bristlenose or uv tool install bristlenosebristlenose doctorChecks FFmpeg, transcription backend, API keys, network, and disk space. Shows fix commands for anything missing.
Bristlenose uses an LLM for the analysis pass (speaker identification, quote extraction, thematic grouping). Transcription is always local. You need one provider:
Best quality. ~$1.50 per study.
bristlenose configure claudeSimilar quality. ~$1.00 per study.
bristlenose configure chatgptAdd --llm openai to your commands to use ChatGPT instead of the default.
Budget option. ~$0.20 per study.
bristlenose configure gemini
bristlenose run interviews --llm geminiFor enterprise teams with Azure contracts.
export BRISTLENOSE_AZURE_ENDPOINT=https://your-resource.openai.azure.com/
export BRISTLENOSE_AZURE_DEPLOYMENT=your-deployment-name
bristlenose configure azureNo API key, no account, no cost. Install Ollama, then run:
bristlenose run interviews --llm localBristlenose will offer to set up Ollama automatically. Trade-off: ~10 minutes vs ~2 minutes per study, lower JSON reliability (~85% vs ~99%).
Keys live in your operating system's secure credential store — never in plaintext.
macOS: Keychain. Linux: Secret Service (GNOME Keyring / KDE Wallet).
Fallback: .env file or environment variables.
# Point at a folder of recordings
bristlenose interviews
# Output appears inside the folder
# interviews/bristlenose-output/
# Open the report in your browser
# macOS: open interviews/bristlenose-output/bristlenose-interviews-report.html
# Linux: xdg-open interviews/bristlenose-output/bristlenose-interviews-report.html
# Windows: start interviews\bristlenose-output\bristlenose-interviews-report.htmlBristlenose accepts any mix of audio (.wav, .mp3, .m4a, .flac, .ogg, .aac), video (.mp4, .mov, .avi, .mkv, .webm), subtitles (.srt, .vtt), and transcripts (.docx from Zoom, Teams, or Google Meet).
Files sharing a name stem (e.g. p1.mp4 and p1.srt)
are treated as one session. Existing subtitles skip transcription.
A typical study (5–8 interviews) takes 2–5 minutes on Apple Silicon.
Each recording is a session. Bristlenose identifies who's speaking: moderators (researchers asking questions — never quoted), participants (the people you're researching — primary data), and observers (silent attendees — excluded from quotes).
Participants get speaker codes (p1, p2) for anonymisation.
You can add display names for your team's reference — these stay internal.
Stakeholders see codes only.
Bristlenose extracts quotable moments from every interview. Filler words are removed.
Meaning, emotion, and self-corrections are preserved. Editorial context is added
sparingly: [clarifying context] only where meaning would be lost.
Each quote appears in exactly one section of the report — no duplicates.
Sections group quotes by screen or task (what the participant was looking at). Themes group quotes by cross-participant pattern (what kept coming up).
Screen-specific quotes go to sections. General-context quotes (job role, daily workflow, broader opinions) go to themes.
Every quote gets AI-generated sentiment tags: positive, negative, neutral, mixed, plus specific emotions (confusion, delight, frustration, trust, skepticism). Signal cards summarise patterns across participants — flagging wins, problems, niggles, and surprises.
Tags are your own codes, applied to quotes as you review them. A codebook organises tags into named groups with colours. You can create your own or import a standard framework:
Bristlenose runs a 12-stage pipeline: ingest → extract audio → parse subtitles → parse transcripts → transcribe → identify speakers → merge transcript → PII removal → topic segmentation → quote extraction → quote clustering → thematic grouping → render.
If a run is interrupted, re-running the same command resumes where it left off. Completed sessions are loaded from cache in milliseconds.
bristlenose serve interviewsOpens an interactive version of your report in the browser. Everything you do is saved to a local database — star quotes, tag, hide noise, edit names, reorganise your codebook. Changes persist between sessions.
Serve mode is the primary way to work with Bristlenose. The static HTML render
(bristlenose render) still works for offline sharing, but serve mode
is where the active development happens.
A codebook is an organised set of tags for analysing your quotes. Each tag belongs to a group, and each group has a colour. You can have multiple codebooks active.
Import a standard UXR framework from the codebook panel: Codebook → Add Framework. Each framework comes with pre-defined groups and tags based on published research methodology.
Create your own groups and tags from the codebook panel. Drag tags between groups, rename groups, set colours. Your codebook is saved to the project database.
Press the ✦ button on a codebook section to let the LLM propose tags for your quotes. Review proposals in a confidence histogram — set a threshold for automatic acceptance, review borderline cases one by one, reject the rest.
| Key | Action |
|---|---|
| j / k | Next / previous quote |
| s | Star focused quote |
| h | Hide focused quote |
| t | Open tag input on focused quote |
| r | Repeat last tag |
| x | Toggle selection on focused quote |
| / | Focus search |
| ? | Help |
| Escape | Clear (cascades: modal → search → selection → focus) |
| [ | Toggle left sidebar (TOC) |
| ] | Toggle right sidebar (tags) |
| \ | Toggle both sidebars |
| m | Toggle inspector panel (Analysis tab) |
| Tab | Commit tag and open new input (fast tagging) |
| Shift+j/k | Extend selection |
| Cmd+click | Multi-select |
| Cmd+, | Settings |
| Command | What it does |
|---|---|
bristlenose run <folder> |
Full pipeline — transcribe, analyse, render. Default command: bristlenose <folder> does the same thing. |
bristlenose serve <folder> |
Interactive browser-based report with live editing and database sync. |
bristlenose transcribe <folder> |
Transcription only — no LLM calls. Useful for checking transcripts before analysis. |
bristlenose analyze <folder> |
Skip transcription, run LLM analysis on existing transcripts. |
bristlenose render <folder> |
Re-render HTML from existing JSON — no LLM calls. For tweaking names or formatting. |
bristlenose status <folder> |
Read-only project status — which stages completed, how many sessions. |
bristlenose doctor |
Check dependencies, API keys, and runtime environment. |
bristlenose configure <provider> |
Store an API key securely. Providers: claude, chatgpt, gemini, azure. |
| Flag | Effect |
|---|---|
-p "Project Name" | Name your project (appears in reports) |
--llm openai | Use ChatGPT instead of Claude |
--llm gemini | Use Gemini |
--llm local | Use Ollama (free) |
--llm azure | Use Azure OpenAI |
--redact-pii | Detect and redact personal information |
--output <dir> | Override default output location |
-y | Skip confirmation prompts |
-v | Verbose terminal output (DEBUG level) |
No Bristlenose server. No accounts. No telemetry. Audio is transcribed locally using Whisper on your machine. The analysis pass sends transcript text to your chosen LLM provider — or stays entirely offline with Ollama.
API keys are stored in your OS credential store (macOS Keychain, Linux Secret Service),
never in plaintext. Fallback to .env or environment variables.
The --redact-pii flag uses Microsoft Presidio + spaCy to detect and redact
names, phone numbers, email addresses, ID numbers, and other personal data.
An audit trail (pii_summary.txt) lists every redaction with confidence scores.
Location names are deliberately excluded — they carry research context.
Two layers of identity. Speaker codes (p1, p2)
are the anonymisation boundary — used in reports by default. Display names
(first names) help your team recall "who's Mary" during analysis. Exports use speaker
codes only, preventing stakeholder bias.
Email security@bristlenose.app. Do not open public GitHub issues for security vulnerabilities.
Recent releases. Full history on GitHub.