tapeback

https://github.com/yastcher/tapeback
Admin
Local meeting recorder with transcription and speaker diarization for Obsidian.
Tokens:9,000
Snippets:109
Trust Score:7.4
License:Apache-2.0
Update:4 months ago
Show doc for...
Tokens:
Raw
### Development Setup Commands

Source: https://github.com/yastcher/tapeback/blob/main/DEPLOY.md

Commands to clone the repository, install development dependencies using uv, and run linting, formatting, type checking, and tests.

```bash
git clone https://github.com/yastcher/tapeback
cd tapeback
uv sync --group dev

uv run ruff check       # lint
uv run ruff format      # format
uv run ty check         # type check
uv run pytest           # test (coverage >= 85%)
```

--------------------------------

### Install tapeback with pip/uv

Source: https://github.com/yastcher/tapeback/blob/main/README.md

Install system dependencies for tapeback on Arch, Ubuntu/Debian, or Fedora. Then, install tapeback and its optional components using uv tool.

```bash
# Arch / Manjaro
sudo pacman -S python uv ffmpeg pipewire-pulse

# Ubuntu / Debian
sudo apt install python3 pipx ffmpeg pulseaudio-utils

# Fedora
sudo dnf install python3 pipx ffmpeg pipewire-pulseaudio

# Then install tapeback:
uv tool install tapeback                          # recording + transcription
uv tool install "tapeback[tray]"                  # + system tray icon
uv tool install "tapeback[llm]"                   # + LLM summaries
uv tool install "tapeback[diarize]"               # + speaker diarization
uv tool install "tapeback[tray,llm,diarize]"      # everything
```

--------------------------------

### Install tapeback on Ubuntu/Debian (.deb)

Source: https://github.com/yastcher/tapeback/blob/main/README.md

Download and install the .deb package for tapeback. Optional packages for tray icon, LLM summaries, and speaker diarization can also be installed.

```bash
wget https://github.com/yastcher/tapeback/releases/download/v0.9.5/tapeback_0.9.5_amd64.deb
sudo apt install ./tapeback_0.9.5_amd64.deb

# Optional extras:
sudo apt install ./tapeback-tray_0.9.5_all.deb       # tray icon
sudo apt install ./tapeback-llm_0.9.5_all.deb        # LLM summaries
sudo apt install ./tapeback-diarize_0.9.5_all.deb    # speaker diarization
```

--------------------------------

### Install AppIndicator Support for GNOME

Source: https://github.com/yastcher/tapeback/blob/main/README.md

Installs the necessary extension for GNOME Shell to display system tray icons. This is a one-time setup required for applications like tapeback, Slack, and Dropbox on Ubuntu/Debian and Fedora systems.

```bash
# Ubuntu / Debian
sudo apt install gnome-shell-extension-appindicator
# Fedora
sudo dnf install gnome-shell-extension-appindicator
```

--------------------------------

### Configure tapeback tray autostart

Source: https://github.com/yastcher/tapeback/blob/main/README.md

Create a .desktop file in ~/.config/autostart to automatically start the tapeback tray application on login.

```ini
[Desktop Entry]
Name=tapeback
Exec=tapeback tray
Type=Application
X-GNOME-Autostart-enabled=true
```

--------------------------------

### Start tapeback recording

Source: https://github.com/yastcher/tapeback/blob/main/README.md

Start the tapeback recording process from the command line. Press Ctrl+C to stop. The transcript will be saved to ~/tapeback/meetings/.

```bash
tapeback start                     # start recording, Ctrl+C to stop
```

--------------------------------

### Install tapeback with pipx or Nix

Source: https://github.com/yastcher/tapeback/blob/main/README.md

Install tapeback using pipx for a virtual environment or Nix for declarative package management. Various options are available for including extra features.

```bash
# pipx
pipx install tapeback
pipx install "tapeback[tray,llm,diarize]"         # everything

# Nix
nix run github:yastcher/tapeback                  # basic
nix run github:yastcher/tapeback#tray             # + system tray icon
nix run github:yastcher/tapeback#llm              # + LLM summaries
nix run github:yastcher/tapeback#diarize          # + speaker diarization
nix run github:yastcher/tapeback#full             # everything
```

--------------------------------

### Tapeback CLI Usage Examples

Source: https://github.com/yastcher/tapeback/blob/main/README.md

Demonstrates various command-line options for tapeback, such as overriding live transcription, skipping diarization or summarization, and specifying providers or models for summarization.

```bash
tapeback start --no-live           # one-shot override: skip live transcription even if TAPEBACK_LIVE=true
tapeback start --no-diarize        # skip speaker identification
tapeback start --no-summarize      # skip LLM summary
tapeback process meeting.mp3 --name "weekly-standup"
tapeback summarize notes.md --provider gemini --model gemini-2.5-pro
```

--------------------------------

### Run tapeback system tray

Source: https://github.com/yastcher/tapeback/blob/main/README.md

Launch the tapeback system tray application. This allows starting and stopping recordings via the tray icon without needing a terminal.

```bash
tapeback tray
```

--------------------------------

### Install tapeback on Arch Linux (AUR)

Source: https://github.com/yastcher/tapeback/blob/main/README.md

Install the base tapeback package for recording and transcription. Additional packages can be added for system tray icon, LLM summaries, or speaker diarization.

```bash
yay -S tapeback                              # recording + transcription
yay -S tapeback tapeback-tray                # + system tray icon
yay -S tapeback tapeback-llm                 # + LLM summaries
yay -S tapeback tapeback-diarize             # + speaker diarization
yay -S tapeback tapeback-tray tapeback-llm tapeback-diarize  # everything
```

--------------------------------

### Tapeback CLI Commands

Source: https://github.com/yastcher/tapeback/blob/main/README.md

Provides a reference for common tapeback command-line interface commands, including starting and stopping recordings, processing files, and generating summaries.

```bash
tapeback start [NAME]              Start recording (Ctrl+C to stop)
tapeback stop                      Stop recording from another terminal
tapeback tray                      System tray icon
tapeback process <FILE> [--name N] Transcribe an existing audio file
tapeback summarize <FILE>          Add LLM summary to transcript
tapeback status                    Show recording status and settings
```

--------------------------------

### Uninstall Tapeback with pip/uv

Source: https://github.com/yastcher/tapeback/blob/main/README.md

Use this command to uninstall tapeback if installed via pip or uv.

```bash
# pip / uv
uv tool uninstall tapeback
```

--------------------------------

### Local Docker Smoke Test on Multiple Distributions

Source: https://github.com/yastcher/tapeback/blob/main/docs/release-testing.md

Runs the tapeback .deb installation and version check across a matrix of older Ubuntu LTS and Debian stable releases to ensure compatibility. This helps catch regressions specific to older environments.

```bash
for img in ubuntu:24.04 ubuntu:22.04 debian:13 debian:12; do
    docker run --rm -v $PWD/dist:/dist "$img" bash -c '
        apt-get update -qq && apt-get install -y -qq /dist/tapeback_*.deb && tapeback --version
    '
done
```

--------------------------------

### Optional Docker Test with LLM Dependencies

Source: https://github.com/yastcher/tapeback/blob/main/docs/release-testing.md

Tests the installation of the tapeback-llm .deb package and verifies that essential Python libraries (anthropic, openai) can be imported from the bundled virtual environment. This is an optional step for testing LLM integration.

```bash
docker run --rm -v $PWD/dist:/dist ubuntu:26.04 bash -c '
    apt-get update -qq
    apt-get install -y -qq /dist/tapeback_*.deb /dist/tapeback-llm_*.deb
    /opt/tapeback/venv/bin/python -c "import anthropic, openai"
'
```

--------------------------------

### Local Docker Smoke Test on Ubuntu LTS

Source: https://github.com/yastcher/tapeback/blob/main/docs/release-testing.md

Installs the tapeback .deb package inside a clean Ubuntu 26.04 container and verifies basic functionality with 'tapeback --version' and 'tapeback status'. This catches common issues like broken shebangs or missing dependencies.

```bash
docker run --rm -v $PWD/dist:/dist ubuntu:26.04 bash -c '
    apt-get update -qq && apt-get install -y -qq /dist/tapeback_*.deb
    tapeback --version
    tapeback status
'
```

--------------------------------

### Tapeback Transcript Output Format

Source: https://github.com/yastcher/tapeback/blob/main/README.md

Example of the markdown output format for tapeback transcripts, including metadata, summary, action items, key decisions, raw transcript with channel labels, and diarized transcript with speaker identification.

```markdown
---
date: 2026-03-23
time: "14:30"
duration: "01:23:45"
language: en
audio: "[[attachments/audio/2026-03-23_14-30-00.wav]]"
tags:
  - meeting
  - transcript
---

## Summary

Brief overview of the meeting.

### Action Items

- [ ] **You:** Send the report by Friday
- [ ] **Speaker 1:** Review the PR

### Key Decisions

- Use PostgreSQL instead of MongoDB

---
# Meeting 2026-03-23 14:30

**Duration:** 1h 23m 45s | **Language:** en

---

## Transcript

[00:00:01] **You:** Hello, let's start with the *backend* changes.

[00:01:23] **Other:** Sure, I have the slides ready.

---

## Diarized Transcript

[00:00:01] **You:** Hello, let's start with the *backend* changes.

[00:01:23] **Speaker 1:** Sure, I have the slides ready.

[00:02:45] **Speaker 1:** Can we move on to the frontend?
```

--------------------------------

### Configure LLM Provider and API Key

Source: https://github.com/yastcher/tapeback/blob/main/README.md

Sets the LLM provider and its corresponding API key in the tapeback environment file for generating summaries. Tapeback can automatically try other providers if the primary one fails.

```bash
TAPEBACK_LLM_PROVIDER=gemini
GEMINI_API_KEY=...
```

--------------------------------

### Build Wheel and DEB Packages

Source: https://github.com/yastcher/tapeback/blob/main/docs/release-testing.md

Builds the tapeback wheel package and then uses it to create .deb packages. This is a prerequisite for the docker smoke tests.

```bash
uv build
./scripts/build-deb.sh dist/tapeback-*.whl
```

--------------------------------

### Tapeback Core Configuration Variables

Source: https://github.com/yastcher/tapeback/blob/main/README.md

Lists core environment variables for tapeback configuration, including paths for the output directory, meeting notes, and audio attachments. These can be set via environment variables or the ~/.config/tapeback/.env file.

```text
Variable | Default | Description
---|---|---
`TAPEBACK_VAULT_PATH` | `~/tapeback` | Path to output directory (Obsidian vault)
`TAPEBACK_MEETINGS_DIR` | `meetings` | Subdirectory for meeting notes
`TAPEBACK_ATTACHMENTS_DIR` | `attachments/audio` | Subdirectory for audio files
```

--------------------------------

### Create and Push Pre-release Tag

Source: https://github.com/yastcher/tapeback/blob/main/docs/release-testing.md

Creates a pre-release Git tag (e.g., v0.9.3-rc1) and pushes it to the origin. This is an optional step for risky changes, allowing for testing of release candidates before the final tag.

```bash
git tag v0.9.3-rc1
git push origin v0.9.3-rc1
```

--------------------------------

### Configure HuggingFace Token for Speaker Diarization

Source: https://github.com/yastcher/tapeback/blob/main/README.md

Sets the HuggingFace token in the tapeback environment file to enable speaker diarization. This requires accepting licenses for pyannote models and creating a token on HuggingFace.

```bash
TAPEBACK_HF_TOKEN=hf_your_token_here
```

--------------------------------

### Configure tapeback to save to Obsidian

Source: https://github.com/yastcher/tapeback/blob/main/README.md

Configure tapeback to save meeting transcripts to your Obsidian vault by creating a .env file in ~/.config/tapeback and setting the TAPEBACK_VAULT_PATH variable.

```bash
mkdir -p ~/.config/tapeback
echo 'TAPEBACK_VAULT_PATH=~/Documents/obsidian/vault' > ~/.config/tapeback/.env
```

--------------------------------

### Tapeback Project Structure

Source: https://github.com/yastcher/tapeback/blob/main/DEPLOY.md

Overview of the directory structure and the primary function of each Python module within the Tapeback project.

```text
src/tapeback/
  cli.py          Click CLI (start, stop, process, summarize, status, tray)
  recorder.py     PulseAudio recording via parecord
  audio.py        ffmpeg audio processing (split channels, normalize, convert)
  transcriber.py  faster-whisper transcription
  diarizer.py     pyannote speaker diarization + spectral speaker merging
  formatter.py    Markdown generation (pure formatting, no I/O)
  vault.py        Obsidian vault file I/O
  tray.py         System tray icon (pystray, optional)
  summarizer.py   LLM summarization with multi-provider fallback
  pipeline.py     End-to-end recording → transcription → output pipeline
  models.py       Domain objects (Segment, Word, DiarizationSegment, Summary)
  settings.py     pydantic-settings configuration
```

--------------------------------

### Release Process Script

Source: https://github.com/yastcher/tapeback/blob/main/DEPLOY.md

Script to automate the release process, including version bumping, committing, tagging, pushing, and updating AUR packages.

```bash
# 1. Bump version in pyproject.toml + all PKGBUILDs
scripts/release.sh 0.9.0

# 2. Commit, tag, push
git add -A && git commit -m "release: 0.9.0"
git tag v0.9.0
git push && git push --tags
# CI publishes to PyPI automatically

# 3. Update AUR packages (after PyPI publish completes)
scripts/aur-publish.sh 0.9.0
```

--------------------------------

### Uninstall Tapeback on Arch Linux

Source: https://github.com/yastcher/tapeback/blob/main/README.md

Use this command to uninstall tapeback and its related packages on Arch Linux.

```bash
# Arch Linux
yay -R tapeback tapeback-tray tapeback-diarize tapeback-llm
```

--------------------------------

### AUR Package Update Script

Source: https://github.com/yastcher/tapeback/blob/main/DEPLOY.md

This script is used to update the Arch User Repository (AUR) packages for Tapeback after a new version is published to PyPI. It handles cloning AUR repositories, copying build files, generating .SRCINFO, and pushing changes.

```bash
scripts/aur-publish.sh 0.9.0
```

--------------------------------

### Remove Cached ML Models

Source: https://github.com/yastcher/tapeback/blob/main/README.md

This command removes cached machine learning models, which can take up significant disk space. Skip if HuggingFace is used for other projects.

```bash
# Remove cached ML models (~2-5 GB)
# Skip if you use HuggingFace for other projects
rm -rf ~/.cache/huggingface/
```
Tokens:
Raw