Metadata-Version: 2.4
Name: clickwheel
Version: 0.9.0
Summary: Sync your music library to a classic iPod from a modern Mac
Project-URL: Homepage, https://github.com/pdugan20/clickwheel
Project-URL: Repository, https://github.com/pdugan20/clickwheel
Project-URL: Issues, https://github.com/pdugan20/clickwheel/issues
Project-URL: Changelog, https://github.com/pdugan20/clickwheel/blob/main/CHANGELOG.md
Author: Pat Dugan
License-Expression: MIT
License-File: LICENSE
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.11
Requires-Dist: mutagen>=1.47
Requires-Dist: pylast>=5.0
Requires-Dist: questionary>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: tqdm>=4.65
Requires-Dist: typer>=0.9
Provides-Extra: artwork
Requires-Dist: numpy>=1.24; extra == 'artwork'
Requires-Dist: pillow>=10.0; extra == 'artwork'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: python-semantic-release>=9.0; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Provides-Extra: fix
Requires-Dist: beets>=2.0; extra == 'fix'
Requires-Dist: pillow>=10.0; extra == 'fix'
Provides-Extra: mcp
Requires-Dist: mcp>=1.2; extra == 'mcp'
Provides-Extra: plex
Requires-Dist: plexapi>=4.18; extra == 'plex'
Description-Content-Type: text/markdown

# clickwheel

[![PyPI](https://img.shields.io/pypi/v/clickwheel?logo=pypi&logoColor=white)](https://pypi.org/project/clickwheel/)
[![CI](https://github.com/pdugan20/clickwheel/actions/workflows/ci.yml/badge.svg)](https://github.com/pdugan20/clickwheel/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/Python-%3E%3D3.11-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?logo=opensourceinitiative&logoColor=white)](https://opensource.org/licenses/MIT)

Sync a music library to a classic iPod from a modern Mac — no iTunes required. Scan, clean up metadata, pick what goes on the iPod, and sync, all from the terminal. Optional MCP server lets Claude or other AI clients drive it conversationally.

## Install

```bash
pipx install clickwheel
```

Optional extras:

```bash
pipx inject clickwheel 'clickwheel[fix]'   # metadata cleanup via beets
pipx inject clickwheel 'clickwheel[mcp]'   # MCP server for Claude / AI clients
```

## Quick Start

Point clickwheel at your music:

```bash
mkdir -p ~/.clickwheel
cat > ~/.clickwheel/config.yaml << 'EOF'
music_dir: /path/to/your/music
EOF
```

Then index it and pick what goes on the iPod:

```bash
clickwheel scan      # build the library index
clickwheel select    # interactive checkbox picker
clickwheel sync      # push to the iPod
```

## Commands

| Command                  | Description                                                                                       |
| ------------------------ | ------------------------------------------------------------------------------------------------- |
| `clickwheel scan`        | Index your music library and report on metadata quality                                           |
| `clickwheel fix`         | Clean up metadata, fetch album art, fill genres via beets                                         |
| `clickwheel select`      | Interactive picker — checkbox artist selection                                                    |
| `clickwheel playlist`    | List saved playlists or show details for one                                                      |
| `clickwheel edit`        | Add/remove artists or set a description (interactive menus or `--add`/`--remove`/`--description`) |
| `clickwheel heal`        | Drop playlist references to tracks no longer on disk                                              |
| `clickwheel delete`      | Delete a saved playlist (with confirmation)                                                       |
| `clickwheel diff`        | Preview what would be added or removed on the iPod                                                |
| `clickwheel sync`        | Push your playlist to the iPod (with live progress table)                                         |
| `clickwheel sync-plex`   | Push playlist(s) to your Plex music library (Plexamp picks them up)                               |
| `clickwheel plex doctor` | Diagnose Plex configuration — one-shot setup check                                                |
| `clickwheel ls`          | Show what's on the iPod                                                                           |
| `clickwheel eject`       | Safely unmount the iPod                                                                           |
| `clickwheel scrobble`    | Submit recent iPod listens to Last.fm                                                             |

## Configuration

```yaml
# ~/.clickwheel/config.yaml
music_dir: /Volumes/Music/Library
ipod_capacity_gb: 64
auto_scan: true
```

Environment variables (`MUSIC_DIR`, `AUTO_SCAN`, etc.) override config values. See [`docs/configuration.md`](docs/configuration.md) for the full schema and `fix` walkthrough.

### Optional integrations

Both off by default; opt in only if you use them.

- **Last.fm scrobbling** — submit iPod listens to Last.fm. See [`docs/lastfm.md`](docs/lastfm.md).
- **Plex / Plexamp** — mirror playlists into a Plex music library so Plexamp picks them up. See [`docs/plex.md`](docs/plex.md).

## MCP server

clickwheel ships an optional MCP server so Claude Code, Claude Desktop, and other MCP-aware clients can drive your library conversationally:

> What's on my iPod, and how full is it?
>
> Build me a 45-minute late-night indie folk playlist using only tracks I actually own.
>
> Sync the 'ipod' playlist to my iPod and then eject it.

Quick start with Claude Code:

```bash
pipx inject clickwheel 'clickwheel[mcp]'
claude mcp add clickwheel clickwheel-mcp --scope user
```

The server exposes 30 tools across library, playlist, iPod, Plex, and Last.fm domains, plus a `build_playlist` prompt with anti-hallucination rules. Destructive operations (`delete_playlist`, `sync_playlist_to_ipod`) are gated by client confirmation.

For Claude Desktop config, the full tool reference, and other clients (Cursor, Continue, Cline, Zed), see [`docs/mcp/`](docs/mcp/).

## Requirements

- macOS (iPod sync depends on macOS disk utilities)
- Python 3.11+
- iPod Classic with stock firmware, connected via USB
- FLAC files are excluded from sync (stock firmware limitation)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, testing, and commit conventions.
