beetbox / beetbox/beets

iTunes-beets bi-directional sync plugin

Open
#1,403 10 comments 0 reactions 0 assignees View on GitHub
feature newplugin
Dominant language
Python
Stars
15.7k
Forks
2.1k
Avg merge
4d 21h
Merged PRs (30d)
31

Description

# Use case

You have an iOS device that you want to use to play and rate songs from your beets library.
# Assumptions
1. Beets is your master library containing your original files, metadata, ratings, and play counts.
2. Because beets is your master library, your iTunes library is disposable (ie. it can be deleted and regenerated on demand from beets).
# Workflow A: Typical Workflow
1. Create a new, empty iTunes library
2. beets itunes_sync
1. Transcodes audio (perhaps using existing Export plugin)
2. Adds tracks to iTunes, with metadata, via AppleScript or Windows SDK.
3. Smart playlists are sent to iTunes as regular playlists
3. You sync iTunes to iOS, play and rate a few tracks.
4. beets itunes_sync
1. Ratings and play counts are written back to beets.
## Notes:
- 4.i can be disabled via the config
- In step 2.ii, a UUID (or a unique beet ID?) is embedded in the exported track's comment field (can be user-definable). This UUID is used to insulate the sync from filename changes.
- We can perform step 4.c accurately if we take a snapshot of the play counts before the sync.
- 2.i is skipped if it already exists in the iTunes library.
- It would be cool to recreate the smart playlists in iTunes in 2.iii, but my guess (haven't looked at code) is that isn't realistic. Is it even supported in iTunes's API?
# Workflow B: Something broke or a configuration changed and you want to force a refresh
1. beets itunes_full_refresh
1. Wipes out all tracks from iTunes and runs itunes_sync
# Further thoughts
- It would be cool to design this in such a way so it's easy to create additional customizations for other media players.
- This plugin's scope is a superset of #1386. It has the following differences:
- #1386 appears to be a one-way sync from a 3rd party player to beets. This plugin would be bi-directional.
- #1386 syncs metadata only and doesn't handle transcoding (necessary since iTunes doesn't support FLAC).
- #1386 appears to store 3rd part player metadata in custom beets fields. In this plugin I propose a customizable mapping is exposed so users can shuffle play count and ratings into whatever beets field they choose.

Contributor guide

Open the contributing guide

Research direction

Review the existing Export plugin and issue #1386 first, then investigate the available iTunes interfaces mentioned in the proposal, including AppleScript and the Windows SDK. Define the plugin's sync, refresh, metadata mapping, transcoding, and playlist scope before implementation; done should include an agreed design and working bi-directional workflow.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.