Add cross-platform support and improve defaults

- Use platformdirs for config path (macOS/Linux/Windows native locations)
- Default output_dir to ~/Downloads instead of current directory
- Fall back to notepad on Windows when $EDITOR is unset
- Add ffmpeg to requirements docs; expand install instructions for all platforms
- Document HuggingFace model cache paths per platform

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: virtuecoder

CLAUDE.md

@@ -0,0 +1,31 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+just install        # create venv and install dependencies via uv
+just run <url>      # transcribe a YouTube URL or bare video ID
+just config --show  # print current config
+just config --edit  # open config in $EDITOR
+just models         # list available Whisper model sizes
+```
+
+There are no tests and no linter configured.
+
+## Architecture
+
+Two source files under `src/transcribe/`:
+
+- **`cli.py`** — all CLI logic via Typer. Two commands: `run` (transcribe) and `config` (show/edit config file). The `run` command tries YouTube captions first (`fetch_youtube_captions`), falls back to Whisper (`transcribe_with_whisper`). Output path resolution order: `--output` flag → `output_dir` in config → `~/Downloads`.
+
+- **`config.py`** — loads `~/.config/yt-transcribe/config.toml` (path determined by `platformdirs.user_config_dir`). Merges user TOML over hardcoded `_DEFAULTS`. Creates the file with documented defaults on `config --edit` if it doesn't exist yet.
+
+## Key behaviours
+
+- `faster-whisper` and `yt-dlp` are lazy imports — only loaded when captions are unavailable, so caption-only runs have no heavy dependency startup cost.
+- Audio is downloaded to `tempfile.TemporaryDirectory()` and deleted automatically after transcription.
+- `unique_path()` appends `(1)`, `(2)`, … to avoid silently overwriting existing files.
+- `--print` suppresses all Rich console output and writes only the transcript to stdout — safe for piping.
+- Config path is platform-specific via `platformdirs`: `~/Library/Application Support/yt-transcribe/` on macOS, `~/.config/yt-transcribe/` on Linux, `%LOCALAPPDATA%\yt-transcribe\` on Windows.

README.md

@@ -5,8 +5,42 @@ CLI tool that extracts transcripts from YouTube videos. Fetches existing caption
 ## Requirements
 
 - Python 3.11+
-- [uv](https://docs.astral.sh/uv/) — `curl -LsSf https://astral.sh/uv/install.sh | sh`
-- [just](https://just.systems/) — `brew install just`
+- [uv](https://docs.astral.sh/uv/)
+- [just](https://just.systems/)
+- [ffmpeg](https://ffmpeg.org/) — required when Whisper is used (no captions available)
+
+### macOS
+
+```bash
+brew install uv just ffmpeg
+```
+
+### Linux (Debian/Ubuntu)
+
+```bash
+# uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# just
+curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
+
+# ffmpeg
+sudo apt install ffmpeg
+```
+
+For other distros replace `apt install ffmpeg` with your package manager (`dnf`, `pacman`, etc.). The `just` binary can also be downloaded from its [GitHub releases](https://github.com/casey/just/releases).
+
+### Windows
+
+```powershell
+winget install astral-sh.uv
+winget install Casey.Just
+winget install ffmpeg
+```
+
+Then restart your terminal so the new PATH entries take effect.
+
+> **Note:** `faster-whisper` requires the [Microsoft Visual C++ Redistributable](https://aka.ms/vs/17/release/vc_redist.x64.exe) (x64). Install it if you see a DLL error on first Whisper run.
 
 ## Setup
 
@@ -18,15 +52,19 @@ just install
 ## Usage
 
 ```bash
-# Fetch captions if available, otherwise run Whisper — saves to current dir by default
+# Fetch captions if available, otherwise run Whisper — saves to ~/Downloads by default
 just run "https://youtube.com/watch?v=VIDEO_ID"
 
 # Save to a specific file
 just run "https://youtube.com/watch?v=VIDEO_ID" --output transcript.txt
 
 # Print to stdout (all status output suppressed — safe to pipe)
 just run "https://youtube.com/watch?v=VIDEO_ID" --print
+
+# Copy to clipboard (macOS: pbcopy, Linux: xclip, Windows: clip)
 just run "https://youtube.com/watch?v=VIDEO_ID" --print | pbcopy
+just run "https://youtube.com/watch?v=VIDEO_ID" --print | xclip -selection clipboard
+just run "https://youtube.com/watch?v=VIDEO_ID" --print | clip
 
 # Force Whisper even if captions exist
 just run "https://youtube.com/watch?v=VIDEO_ID" --force-whisper
@@ -43,12 +81,18 @@ just models
 
 ## Config
 
-Defaults are stored in `~/.config/yt-transcribe/config.toml`. On first run with `just config --edit` the file is created with all options documented inline.
+Defaults are stored in a platform-specific config file:
+
+| Platform | Path |
+|---|---|
+| macOS | `~/Library/Application Support/yt-transcribe/config.toml` |
+| Linux | `~/.config/yt-transcribe/config.toml` |
+| Windows | `%LOCALAPPDATA%\yt-transcribe\config.toml` |
 
 ```bash
 just config           # show config file path
 just config --show    # print current config
-just config --edit    # open in $EDITOR
+just config --edit    # open in $EDITOR (or notepad on Windows)
 ```
 
 Default config:
@@ -57,7 +101,7 @@ Default config:
 [defaults]
 model = "turbo"         # tiny | base | small | medium | turbo | large-v3
 language = ""           # empty = auto-detect per video
-output_dir = ""         # if set, transcripts are auto-saved here (uses video title as filename)
+output_dir = "~/Downloads"  # transcripts are auto-saved here (uses video title as filename)
 output_extension = "txt"
 
 [whisper]
@@ -67,7 +111,7 @@ beam_size = 5           # higher = more accurate, slower (1–10)
 vad_filter = true       # skip silent segments (recommended)
 ```
 
-**`output_dir`** — when set, every transcription is auto-saved to `<output_dir>/<video title>.<output_extension>` without needing `--output`. Useful for batch use.
+**`output_dir`** — when set, every transcription is auto-saved to `<output_dir>/<video title>.<output_extension>` without needing `--output`. Useful for batch use. Supports `~` expansion.
 
 ## Options
 
@@ -79,13 +123,13 @@ vad_filter = true       # skip silent segments (recommended)
 | `--language` | `-l` | auto-detect | Override language, e.g. `en`, `fr`, `de`. Omit to auto-detect — useful only when detection gets it wrong or the video has mixed-language content. |
 | `--force-whisper` | `-w` | off | Skip caption lookup, always use Whisper |
 
-By default the transcript is **saved to a file** — to `output_dir` from config if set, otherwise to the current directory, using the video title as the filename. Use `--print` to get stdout behaviour instead.
+By default the transcript is **saved to `~/Downloads`** using the video title as the filename. Change `output_dir` in config to save elsewhere. Use `--print` to get stdout behaviour instead.
 
 CLI flags always override config values.
 
 ## Whisper models
 
-Model weights are downloaded from HuggingFace on first use and cached at `~/.cache/huggingface/hub/`. Subsequent runs use the cached copy — no re-download. Override the location with the `HF_HUB_CACHE` environment variable.
+Model weights are downloaded from HuggingFace on first use and cached at `~/.cache/huggingface/hub/` (macOS/Linux) or `%USERPROFILE%\.cache\huggingface\hub\` (Windows). Subsequent runs use the cached copy — no re-download. Override with the `HF_HUB_CACHE` environment variable.
 
 | Model | Size | Speed | Accuracy |
 |---|---|---|---|
@@ -115,7 +159,7 @@ Model weights are downloaded from HuggingFace on first use and cached at `~/.cac
            Yes: done                  No: fallback
                                            │
                                     ┌──────▼──────┐
-                                    │  Download   │  ◄── yt-dlp
+                                    │  Download   │  ◄── yt-dlp + ffmpeg
                                     │  audio      │      best quality stream
                                     └──────┬──────┘
                                            │
@@ -155,3 +199,4 @@ Uses [`youtube-transcript-api`](https://github.com/jdepoix/youtube-transcript-ap
 | [`faster-whisper`](https://github.com/SYSTRAN/faster-whisper) | Local speech-to-text |
 | [`typer`](https://typer.tiangolo.com/) | CLI framework |
 | [`rich`](https://rich.readthedocs.io/) | Terminal output |
+| [`platformdirs`](https://platformdirs.readthedocs.io/) | Platform-appropriate config paths |

pyproject.toml

@@ -9,6 +9,7 @@ dependencies = [
     "faster-whisper>=1.2.0",
     "typer>=0.12.0",
     "rich>=13.0.0",
+    "platformdirs>=4.0.0",
 ]
 
 [project.scripts]

src/transcribe/cli.py

@@ -227,7 +227,9 @@ def config_cmd(
     if edit:
         import os
         import subprocess
-        editor = os.environ.get("EDITOR", "nano")
+        import sys
+        default_editor = "notepad" if sys.platform == "win32" else "nano"
+        editor = os.environ.get("EDITOR", default_editor)
         subprocess.run([editor, str(path)])
     elif show:
         _console.print(path.read_text())

src/transcribe/config.py

@@ -7,14 +7,16 @@
 from pathlib import Path
 from typing import Any
 
-CONFIG_PATH = Path.home() / ".config" / "yt-transcribe" / "config.toml"
+from platformdirs import user_config_dir
+
+CONFIG_PATH = Path(user_config_dir("yt-transcribe")) / "config.toml"
 
 # Written on first run if the file doesn't exist yet.
 _DEFAULT_TOML = """\
 [defaults]
 model = "turbo"         # tiny | base | small | medium | turbo | large-v3
 language = ""           # empty = auto-detect per video
-output_dir = ""         # if set, transcripts are auto-saved here (uses video title as filename)
+output_dir = "~/Downloads"  # transcripts are auto-saved here (uses video title as filename)
 output_extension = "txt"
 
 [whisper]
@@ -28,7 +30,7 @@
     "defaults": {
         "model": "turbo",
         "language": "",
-        "output_dir": "",
+        "output_dir": "~/Downloads",
         "output_extension": "txt",
     },
     "whisper": {