Live transcription

.github/actions/quality-checks/action.yml

@@ -55,7 +55,7 @@ runs:
     - name: Run type checking
       shell: bash
       run: |
-        uv run mypy chirp config recorder transcriber notes utils --ignore-missing-imports
+        uv run mypy
 
     - name: Validate code compilation
       shell: bash

.vscode/settings.json

@@ -45,6 +45,7 @@
     "isort",
     "mypy",
     "nomic",
+    "noreverse",
     "ollama",
     "portaudio",
     "pyaudio",

AGENTS.md

@@ -4,13 +4,21 @@
 Chirp is a Python CLI whose runtime code lives under `chirp/` with Typer commands in `chirp/cli.py`. Recorder, transcription, note generation, and chat pipelines live in sibling packages (`recorder/`, `transcriber/`, `notes/`, `notes_chat/`, `utils/`) and share Pydantic config from `config/settings.py`. Markdown templates sit in `templates/`, while runtime artifacts land in `to-transcribe/`, `transcription-out/`, and `notes-out/`. Tests mirror the domains in `tests/` (e.g., `tests/test_note_generator.py`), so add new coverage alongside the feature.
 
 ## Build, Test & Development Commands
-Use `make dev-install` once to sync dependencies with `uv` and install pre-commit hooks. Day-to-day, run `make lint`, `make format`, and `make type-check` before pushing; `make check` chains the validation helpers. Run the full suite with `make test` or `make test-coverage` when you need HTML coverage reports. Use `uv run chirp status` to verify your environment, and `make process` for an end-to-end functional smoke.
+**Setup:** `make dev-install` (installs deps with `uv` and pre-commit hooks).
+**Quality checks:** `make check` chains `validate`, `lint`, `format-check`, `spell-check`, and `type-check`. Run `make lint-fix` and `make format` to auto-fix issues before pushing.
+**Testing:** `make test` runs pytest; `make test-coverage` generates HTML reports. Run a single test with `uv run pytest tests/test_note_generator.py` or a specific function with `uv run pytest tests/test_note_generator.py::test_function_name`. Use `make test-failed` to re-run only failures.
+**Validation:** `uv run chirp status` verifies environment; `make process` smoke-tests the full pipeline (record → transcribe → notes).
 
 ## Coding Style & Naming Conventions
-Ruff enforces formatting (88-char lines, double quotes, spaces for indent), so run `make format` after major edits. Prefer descriptive module-level functions and keep CLI command names terse (see `chirp/cli.py`). Name files and functions after the domain action (`*_manager`, `*_processor`). Follow "Clean Code" guidance: keep logic readable, avoid unnecessary comments, and document only intent that code cannot express. Type hints are encouraged; mypy runs against key packages, so silence warnings with actual annotations instead of `type: ignore`.
+**Formatting:** Ruff enforces 88-char lines, double quotes, space indents (run `make format` after edits). Pre-commit hooks auto-fix ruff, codespell, trailing whitespace, and YAML.
+**Imports:** Group stdlib, third-party, and first-party (`chirp`, `config`, `notes`, etc.) via isort. Use absolute imports; avoid star imports except for exceptions.
+**Naming:** Files and functions follow domain actions (`*_manager`, `*_processor`). CLI commands stay terse (see `chirp/cli.py`). Classes use PascalCase; functions/vars use snake_case.
+**Types:** Type hints encouraged; mypy checks `chirp`, `config`, `notes`, `notes_chat`, `recorder`, `transcriber`, `utils`. Silence warnings with annotations, not `type: ignore`.
+**Comments:** Avoid unnecessary comments; write self-documenting code. Document only non-obvious intent that code cannot express.
+**Error handling:** Raise custom exceptions from `chirp.exceptions` for domain errors; use generic exceptions sparingly.
 
 ## Testing Guidelines
-Write `pytest` tests in `tests/` with filenames starting `test_` and functions mirroring user-facing behavior. Use fixtures to stub audio and Ollama integrations; see `tests/test_audio_recorder.py` and `tests/notes_chat/` for patterns. When adding asynchronous or long-running flows, include a fast unit test and, if needed, a skipped integration marked with a reason. Keep coverage above existing baselines by running `make test-coverage` locally.
+Write `pytest` tests in `tests/` with filenames starting `test_` and functions mirroring user-facing behavior. Use fixtures to stub audio and Ollama integrations; see `tests/test_audio_recorder.py` and `tests/notes_chat/` for patterns. Mark slow or integration tests with `@pytest.mark.slow` or `@pytest.mark.integration`; skip with `@pytest.mark.skip(reason="...")` if needed. Keep coverage above existing baselines by running `make test-coverage` locally.
 
 ## Commit & Pull Request Guidelines
-Commit subjects follow the short, imperative style already in history (e.g., `Add file name override option`). Group related changes and include meaningful bodies when context is not obvious. Before opening a PR, ensure `make check` and `make test` pass, link any GitHub issues, and describe runtime impacts. Screenshots or sample CLI output help reviewers validate UX changes; attach them when modifying prompts or note templates.
+Commit subjects follow the short, imperative style (e.g., `Add file name override option`). Group related changes; include meaningful bodies when context is not obvious. Before opening a PR, ensure `make check` and `make test` pass, link any GitHub issues, and describe runtime impacts. Screenshots or sample CLI output help reviewers validate UX changes; attach them when modifying prompts or note templates.

CLAUDE.md

@@ -6,8 +6,9 @@
 
 ### Core Functionality
 
-- **Audio Recording**: High-quality meeting recording with system audio capture
-- **Transcription**: Speech-to-text using OpenAI's Whisper models
+- **Audio Recording**: High-quality meeting recording with system audio capture (uses default input device)
+- **Live Transcription**: Real-time transcription with scrollable dashboard during recording
+- **Transcription**: Speech-to-text using OpenAI's Whisper models (large-v3-turbo)
 - **AI Notes**: Generate structured meeting summaries using Ollama LLMs
 - **Semantic Search**: Query meeting notes with ChromaDB vector search
 - **Interactive Chat**: Ask questions about meeting content
@@ -26,18 +27,19 @@
 
 - **`chirp/`**: Main CLI module with Typer commands
 - **`config/`**: Settings management with Pydantic and platform-specific paths
-- **`recorder/`**: Audio recording with PyAudio and device management
-- **`transcriber/`**: Whisper-based transcription with batch processing
+- **`recorder/`**: Audio recording with PyAudio, device management, live transcription with scrollable dashboard
+- **`transcriber/`**: Whisper-based transcription with batch processing and streaming support
 - **`notes/`**: AI note generation using Ollama
 - **`notes_chat/`**: Semantic search and interactive chat features
 - **`utils/`**: Shared utilities for file operations and time handling
 
 ### External Dependencies
 
-- **Audio**: PyAudio, PortAudio (system), BlackHole (macOS)
-- **AI Models**: Ollama (llama3.1:8b, nomic-embed-text)
+- **Audio**: PyAudio, PortAudio (system), optional BlackHole/aggregate devices (macOS)
+- **AI Models**: Ollama (llama3.1:8b for notes, nomic-embed-text for search), faster-whisper (large-v3-turbo)
 - **Database**: ChromaDB for vector search
-- **CLI**: Typer with Rich for beautiful terminal output
+- **CLI**: Typer with Rich for beautiful terminal output, including scrollable live dashboard
+- **VAD**: WebRTC VAD for speech detection in live transcription
 
 ## Development Guidelines
 

Makefile

@@ -1,8 +1,8 @@
-.PHONY: help install dev-install test lint format type-check clean run build setup-blackhole check-deps
+.PHONY: help install dev-install test lint format type-check clean run build setup check-deps
 
 # Default help command
 help: ## Show this help message
-	@echo "🐦 Chirp Development Makefile"
+	@echo "🐣 Chirp Development Makefile"
 	@echo ""
 	@echo "Available commands:"
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2}'
@@ -48,15 +48,14 @@ notes: ## Generate meeting notes
 process: ## Process audio files (transcribe + notes)
 	uv run chirp process $(if $(FORCE),--force)
 
-ask: ## Ask with your notes
-	uv run chirp ask
+ask: ## Start interactive chat with your notes
+	uv run chirp notes ask
 
-# Notes search commands
 notes-index: ## Build notes search index
-	uv run notes index $(if $(FORCE),--force)
+	uv run chirp notes index $(if $(FORCE),--force)
 
 notes-ask: ## Ask a question about your notes (requires QUESTION)
-	uv run notes ask "$(QUESTION)" $(if $(WHEN),--when "$(WHEN)")
+	uv run chirp notes ask --question "$(QUESTION)" $(if $(WHEN),--when "$(WHEN)")
 
 status: ## Show Chirp status
 	uv run chirp status
@@ -69,13 +68,17 @@ devices: ## List audio devices
 
 # Testing commands
 test: ## Run unit tests
-	uv run pytest tests/ -v
+	uv run pytest
 
 test-coverage: ## Run tests with coverage report
-	uv run pytest tests/ -v --cov=chirp --cov=config --cov=recorder --cov=transcriber --cov=notes --cov=notes_chat --cov=utils --cov-report=html --cov-report=term
+	uv run pytest --cov --cov-report=html --cov-report=term
+
+test-failed: ## Run only failed tests from last run
+	uv run pytest --lf
+
+test-verbose: ## Run tests with verbose output
+	uv run pytest -vv
 
-test-watch: ## Run tests in watch mode
-	uv run pytest-watch tests/ --clear
 
 # Code quality commands
 lint: ## Run linting with ruff
@@ -100,7 +103,7 @@ style-check: ## Check linting, formatting, and spelling
 	@$(MAKE) spell-check
 
 type-check: ## Run type checking with mypy
-	uv run mypy chirp config recorder transcriber notes notes_chat utils --ignore-missing-imports
+	uv run mypy
 
 spell-check: ## Check spelling with codespell
 	uv run codespell
@@ -120,6 +123,8 @@ validate: ## Validate code compiles and imports work
 # Quality check combination
 check: validate style-check type-check ## Run all quality checks (excluding tests)
 
+ci: lint format-check type-check test ## Run CI checks (lint, format, type-check, test)
+
 # Dependency management
 check-deps: ## Check if all dependencies are available
 	uv run chirp test
@@ -128,17 +133,14 @@ update: ## Update dependencies
 	uv sync --upgrade
 
 # Setup commands
-setup: install setup-dirs ## Initial setup for new installations
+setup: install ## Initial setup for new installations
 	uv run pre-commit install
 	@echo "✅ Chirp setup complete!"
 	@echo "Next steps:"
 	@echo "  1. Install BlackHole: make setup-blackhole"
 	@echo "  2. Install Ollama: make setup-ollama"
 	@echo "  3. Run 'make check-deps' to verify setup"
 
-setup-dirs: ## Create required directories
-	mkdir -p to-transcribe transcription-out notes-out config templates
-
 setup-blackhole: ## Show BlackHole installation instructions
 	@echo "🎵 BlackHole Audio Driver Installation"
 	@echo ""
@@ -172,12 +174,6 @@ setup-ollama: ## Show Ollama setup instructions
 build: ## Build package
 	uv build
 
-# Docker commands (optional)
-docker-build: ## Build Docker image
-	docker build -t chirp:latest .
-
-docker-run: ## Run Chirp in Docker container
-	docker run -it --rm -v $(PWD)/to-transcribe:/app/to-transcribe -v $(PWD)/transcription-out:/app/transcription-out -v $(PWD)/notes-out:/app/notes-out chirp:latest
 
 # Cleaning commands
 clean: ## Clean build artifacts and cache
@@ -190,19 +186,7 @@ clean: ## Clean build artifacts and cache
 	find . -type d -name __pycache__ -exec rm -rf {} +
 	find . -type f -name "*.pyc" -delete
 
-clean-audio: ## Clean audio files (be careful!)
-	@echo "⚠️  This will delete all audio files. Are you sure? (y/N)"
-	@read confirmation && [ "$$confirmation" = "y" ] && rm -rf to-transcribe/*.wav to-transcribe/*.m4a to-transcribe/*.mp3
-
-clean-transcriptions: ## Clean transcription files
-	@echo "⚠️  This will delete all transcription files. Are you sure? (y/N)"
-	@read confirmation && [ "$$confirmation" = "y" ] && rm -rf transcription-out/*.json.gz
-
-clean-notes: ## Clean generated notes
-	@echo "⚠️  This will delete all generated notes. Are you sure? (y/N)"
-	@read confirmation && [ "$$confirmation" = "y" ] && rm -rf notes-out/*.md
-
-clean-all: clean clean-audio clean-transcriptions clean-notes ## Clean everything (DANGEROUS!)
+clean-all: clean ## Clean everything including build artifacts
 
 # Development workflow shortcuts
 dev-workflow: ## Complete development workflow (style, type-check, test, build)
@@ -226,15 +210,15 @@ demo: ## Run a complete demo workflow
 	@echo "✅ Demo complete! Ready to record with 'make record'"
 
 # Documentation
-docs: ## Generate documentation (if implemented)
-	@echo "📚 Documentation generation not yet implemented"
-	@echo "Current documentation:"
-	@echo "  - README.md"
+docs: ## Show documentation locations
+	@echo "📚 Chirp Documentation:"
+	@echo "  - README.md - Main documentation"
+	@echo "  - .docs/DEVELOPMENT.md - Developer guide"
 	@echo "  - CLI help: uv run chirp --help"
 
 # System information
 info: ## Show system and version information
-	@echo "🐦 Chirp System Information:"
+	@echo "🐣 Chirp System Information:"
 	@echo "Python: $(shell python --version)"
 	@echo "UV: $(shell uv --version)"
 	@echo "Project: $(shell grep '^version' pyproject.toml | cut -d'"' -f2)"

README.md

@@ -1,4 +1,4 @@
-# 🐦 Chirp - AI Meeting Notes CLI
+# 🐣 Chirp - AI Meeting Notes CLI
 
 <!-- markdownlint-disable MD033 -->
 <p align="center">
@@ -10,7 +10,8 @@
 
 ## ✨ Features
 
-- **🎙️ System Audio Recording**: Capture high-quality audio from meetings, calls, or any system audio using BlackHole
+- **🎙️ System Audio Recording**: Capture high-quality audio from meetings, calls, or any system audio
+- **📺 Live Transcription**: Real-time transcription with scrollable dashboard while recording
 - **🤖 AI Transcription**: Powered by faster-whisper with Apple Silicon optimization for accurate speech-to-text
 - **📋 Smart Note Generation**: Uses Ollama + Llama 3.1 to generate structured meeting notes with key points, decisions, and action items
 - **📁 Batch Processing**: Process multiple audio files with progress indicators
@@ -35,18 +36,28 @@ brew install chirp
 chirp setup
 ```
 
-### Install BlackHole audio driver
+### Setup Audio Input Device
 
+Chirp uses your system's default input device for recording. You have several options:
+
+**Option 1: Use an Aggregate Device (Recommended for system audio + microphone)**
+- Open Audio MIDI Setup (Applications/Utilities)
+- Create an Aggregate Device combining:
+  - Your microphone (for your voice)
+  - BlackHole (for system audio)
+- Set this aggregate device as your default input in System Settings → Sound
+
+**Option 2: Use BlackHole Only (System audio only)**
 ```bash
-# Install Blackhole
+# Install BlackHole
 brew install blackhole-2ch
 ```
+- Set BlackHole as your default input device
+- Create a Multi-Output Device to hear audio while recording
 
-- Set up a multi-output device using `Audio MIDI Setup`:
-  - Open Audio MIDI Setup (Applications/Utilities)
-  - Create a Multi-Output Device
-  - Include both your speakers and BlackHole
-  - Set this as your default output device
+**Option 3: Use Built-in Microphone**
+- Just use your Mac's built-in microphone (no setup needed)
+- Set it as default input in System Settings → Sound
 
 ### Setup Ollama and AI Models
 
@@ -129,10 +140,29 @@ chirp record --duration 30 --title "Client Meeting"
 # Record indefinitely (stop with Ctrl+C)
 chirp record
 
+# Record with live transcription (real-time transcription while recording)
+chirp record --live-transcribe --title "Team Meeting"
+
 # Record with custom settings
 chirp record -d 45 -t "Project Planning"
 ```
 
+#### Live Transcription Mode
+
+When using `--live-transcribe`, you get a real-time dashboard showing:
+
+- **Live transcript**: See the transcription as it happens
+- **Audio levels**: Visual feedback of recording volume
+- **Speaker detection**: See when speech is detected
+- **Scrollable view**: Use arrow keys to scroll through the transcript while recording continues
+
+**Keyboard Controls During Live Transcription**:
+- `↑/↓` or `PgUp/PgDn`: Scroll through the transcript
+- `Space` or `Enter`: Jump back to latest transcription (resume auto-scroll)
+- `Ctrl+C`: Stop recording and save
+
+**Note**: Live transcription uses the `large-v3-turbo` Whisper model and provides near real-time results. The final high-quality transcript can be generated afterward with `chirp transcribe`.
+
 ### Processing Audio
 
 ```bash
@@ -248,17 +278,24 @@ chirp status
 
 ### Audio Recording Issues
 
-**BlackHole not detected**:
+**No audio being recorded**:
 
-1. Download and install BlackHole from [existential.audio/blackhole](https://existential.audio/blackhole/)
-2. Set up a multi-output device in Audio MIDI Setup
-3. Verify detection: `chirp devices`
+1. Check your default input device in System Settings → Sound
+2. Verify the device is working: `chirp devices`
+3. Check audio permissions in System Preferences > Security & Privacy > Microphone
 
 **Recording fails to start**:
 
 1. Check audio permissions in System Preferences > Security & Privacy > Microphone
-2. Verify BlackHole installation: `chirp test`
+2. Verify your default input device is set correctly
 3. List available devices: `chirp devices`
+4. Try a different input device
+
+**Want to record system audio**:
+
+1. Install BlackHole: `brew install blackhole-2ch`
+2. Create an Aggregate Device in Audio MIDI Setup
+3. Set the aggregate device as your default input
 
 ### AI/LLM Issues
 
@@ -286,12 +323,12 @@ chirp status
 
 ### Near-term
 
-- **Speaker Detection**: Identify different speakers in meetings
+- **Speaker Diarization**: Identify and label different speakers in meetings
+- **Streaming Transcription**: Segment-by-segment streaming display
 
 ### Long-term
 
 - **Calendar Integration**: Auto-trigger recording from macOS Calendar
-- **Real-time Transcription**: Live transcription during recording
 - **Multiple Export Formats**: PDF, DOCX, Notion, etc.
 - **Meeting Analytics**: Insights and patterns from meeting data
 - **OS Support**: Support Windows and Linux