Metadata-Version: 2.4
Name: lib-sync
Version: 0.2.0
Summary: A collection of tools for managing your music library
Author-email: Josh Lebedinsky <joshlebed@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/clobraico22/lib-sync
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: spotipy==2.23.0
Requires-Dist: python-dotenv==1.0.0
Requires-Dist: yt-dlp==2025.06.09
Requires-Dist: aiohttp==3.9.3
Requires-Dist: colorama==0.4.6
Requires-Dist: tqdm==4.62.3
Requires-Dist: shazamio==0.7.0

# Lib-Sync

libsync has some useful tools for managing your music library.

- `sync` syncs your rekordbox playlists to spotify playlists.
- `analyze` analyzes your rekordbox library.
- `id` identifies songs from a recording or youtube set.

## User Guide

### Prerequisites

- [python 3.11](https://www.python.org/downloads/release/python-31010/) installed locally
- `.env` file in the root directory with client ID and secret
  - go to the [Spotify developers dashboard](https://developer.spotify.com/dashboard) and go to Create App to get a client ID and secret
  - copy `.example.env` from this directory into a new file `.env` in the same directory and add your `id` and `secret`
- [`ffmpeg`](https://www.ffmpeg.org/download.html) installed and available on the path

### Setup

In this directory, run:

```bash
python3.11 -m venv .venv   # create virtual environment
source .venv/bin/activate  # activate virtual environment
pip install -e ".[dev]"    # install dependencies locally
```

### Sync

From the rekordbox application, export your library as xml (remember where you save the file). Then run:

```bash
python -m libsync sync -h   # display help page

python -m libsync sync \
--rekordbox_xml_path ${HOME}/Documents/rekordbox/rekordbox_export.xml \
--create_collection_playlist
```

#### Manually Fixing the Mappings

After running the sync command at least once for your library, you can update the `spotify URL (input)` column in the `data/*.csv` file generated by libsync. Just paste in the track's spotify URL in the `Spotify URL (input)` column. Then next time you sync, libsync will pick up those new mappings and update your playlists. You can also manually update the `Spotify URI` column with `libsync:NOT_ON_SPOTIFY` for songs you know are not on Spotify, so libsync knows to stop looking for it.

If you want libsync to redo the auto mapping process for a previously analyzed song, you can tag it with a `1` in the `Retry auto match (input)` column in the csv. This can be useful if a song is newly posted on Spotify, or to take advantage of libsync improvements. This will override the `libsync:NOT_ON_SPOTIFY` flag. Use this with the `--ignore_spotify_search_cache` command line flag to hit the network again instead of just using the cache and running the matching algorithm again.

### Analyze

```bash
python -m libsync analyze -h
```

## Dev Guide

### Quickstart

**One time setup**

```bash
python -m venv .venv   # create virtual environment
```

**Each time you pull a new version**

```bash
source .venv/bin/activate  # activate virtual environment
pip install -e ".[dev]"    # install dependencies locally
pre-commit install         # install pre-commit hooks
```

**To add useful dev shell commands**

Add the following to your `.bashrc` or `.zshrc`:

```bash
LIBSYNC_REPO_DIRECTORY='/Users/joshlebed/code/lib-sync' # update to the path to the repo on your machine
alias libsync-dev="${LIBSYNC_REPO_DIRECTORY}/.venv/bin/python -m libsync"
alias libsync-run-sync="cd ${LIBSYNC_REPO_DIRECTORY} && ${LIBSYNC_REPO_DIRECTORY}/scripts/run_sync.sh"
```

**To run with sample data:**

```bash
python -m libsync --verbose --verbose \
sync \
--rekordbox_xml_path sample_data/example_rekordbox_export.xml \
--create_collection_playlist
```

Use `--verbose` or `-v` before the subcommand to increase the verbosity of logging to the console.
Use one `-v` for INFO level, two for DEBUG level.

**To run with prod data:**

```bash
python -m libsync --verbose --verbose \
sync \
--rekordbox_xml_path ${HOME}/Documents/rekordbox/rekordbox_export.xml \
--create_collection_playlist
```

**To run analysis command:**

```bash
python -m libsync analyze \
--rekordbox_xml_path sample_data/example_rekordbox_export.xml \

python -m libsync analyze \
--rekordbox_xml_path ${HOME}/Documents/rekordbox/rekordbox_export.xml
```

**To run id command:**

```bash
python -m libsync id file \
--recording_audio_file_path sample_data/file.mp3 \
```

```bash
python -m libsync id youtube \
--youtube_url https://www.youtube.com/watch\?v\=6qSnO5U95yU \
```

## Linting/Formatting

[TODO]

# TODO

## features

- support deleting tracks from rekordbox - libsync doesn't know it was deleted manually, so it will report that the song is missing from the rekordbox playlist. need to keep track of rekordbox collection history to track deletions
- support read-only playlists - like "to be tagged" - ignore these when syncing from spotify back to rekordbox
- multithread shazam process
- connect id tool to spotify mapper and playlist creator

## dev

- get markdown autoformatter
- fix structure/imports with https://github.com/jgehrcke/python-cmdline-bootstrap
