This tool bridges the gap between Plex Media Server and your audio files, ensuring your carefully curated ratings are preserved and synchronized between Plex and your preferred music player. Supports various rating schemes including those used by MusicBee, MediaMonkey, Picard, and other popular players or tools.

• Bidirectional sync between Plex and audio files
• Import and export ratings between Plex and audio files
• Support for both half-star and full-star ratings
• Supports MP3 (ID3v2), FLAC, M4A (AAC/ALAC), OGG, and Opus formats
• Support for multiple Plex music libraries
• Compatible with rating schemes from multiple applications
• Dry-run mode to preview changes without applying them
• Detailed logging with customizable verbosity levels

Start by installing the latest version:

pipx install PlexMusicRatingsSync

Or, install specific a version:

pipx install PlexMusicRatingsSync==x.y.z --force

And, to upgrade to the latest version:

pipx upgrade PlexMusicRatingsSync

Start by checking your system information and locating your config file:

plex-music-ratings-sync info

• This command creates a configuration file (the path is shown in the output) with placeholders and some initial settings. You’ll need to edit that file to add your own values before the script can run properly.

Now you’re ready to run any of the available commands, that you can view with:

plex-music-ratings-sync --help

• For detailed information about any specific command, use:

  plex-music-ratings-sync COMMAND --help
  

  • Replace COMMAND with the command (e.g., sync, import, export) you want to learn more about.

Lastly, synchronize ratings between Plex and your audio files with:

plex-music-ratings-sync sync

• Or import ratings from audio files into Plex with:

  plex-music-ratings-sync import
  

• Or export ratings from Plex to audio files with:

  plex-music-ratings-sync export
  

Start by setting up your docker-compose.yml like this:

services:
  plex-music-ratings-sync:
    image: ghcr.io/rfgamaral/plex-music-ratings-sync
    container_name: plex-music-ratings-sync
    network_mode: bridge
    restart: on-failure:2
    volumes:
      - /host/app/data:/app/data
      - /host/plex/music:/plex/music

• For a specific version (e.g., 1.2.3):
  • ghcr.io/rfgamaral/plex-music-ratings-sync:1.2.3
• For the latest patch of a minor version (e.g., 1.2):
  • ghcr.io/rfgamaral/plex-music-ratings-sync:1.2
• For the latest patch of a major version (e.g., 1):
  • ghcr.io/rfgamaral/plex-music-ratings-sync:1

Then run the following Docker Compose command:

docker compose run --rm plex-music-ratings-sync info

• This creates a config file with placeholders and initial settings; which you must edit before the script can run. Thanks to the volume mount, it’s saved on your host path (though the container output will show an internal path).

Now you’re ready to run any of the available commands, that you can view with:

docker compose run --rm plex-music-ratings-sync --help

• For detailed information about any specific command, use:

  docker compose run --rm plex-music-ratings-sync COMMAND --help
  

  • Replace COMMAND with the command (e.g., sync, import, export) you want to learn more about.

Lastly, synchronize ratings between Plex and your audio files with:

docker compose run --rm plex-music-ratings-sync sync

• Or import ratings from audio files into Plex with:

  docker compose run --rm plex-music-ratings-sync import
  

• Or export ratings from Plex to audio files with:

  docker compose run --rm plex-music-ratings-sync export
  

You can automate the synchronization process to run periodically using different methods depending on your installation.

If you installed the app via pipx, add a cron job to run the sync command:

# Edit your crontab
crontab -e

# Add one of these lines:

# Run daily at 03:00
0 3 * * * $HOME/.local/bin/plex-music-ratings-sync sync

# Run weekly on Sunday at 03:00
0 3 * * 0 $HOME/.local/bin/plex-music-ratings-sync sync

# Run monthly on the 1st at 03:00
0 3 1 * * $HOME/.local/bin/plex-music-ratings-sync sync

If you installed the app via pipx on Windows, create a scheduled task:

1. Open Task Scheduler
2. Click "Create Basic Task"
3. Set a name and description
4. Choose your trigger (Daily, Weekly, etc.)
5. For the action, select "Start a program"
6. Program/script: %USERPROFILE%\.local\bin\plex-music-ratings-sync.exe
7. Arguments: sync

If you’re using Docker, you can use set up your docker-compose.yml with Ofelia as a job scheduler. Here’s an example to synchronize ratings between Plex and your audio files every 6 hours:

services:
  plex-music-ratings-sync:
    image: ghcr.io/rfgamaral/plex-music-ratings-sync
    container_name: plex-music-ratings-sync
    network_mode: bridge
    command: sync
    restart: on-failure:2
    volumes:
      - /host/app/data:/app/data
      - /host/plex/music:/plex/music
  ofelia-scheduler:
    image: mcuadros/ofelia
    container_name: ofelia-scheduler
    command: daemon --docker
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    labels:
      ofelia.job-run.plex-music-ratings-sync.schedule: '@every 6h'
      ofelia.job-run.plex-music-ratings-sync.container: 'plex-music-ratings-sync'

First, create both services without starting them:

docker compose up --no-start

Next, start only the ofelia-scheduler service:

docker compose up ofelia-scheduler

You can verify the correct path in Plex by opening any track in your library, clicking the ⋮ (three dots) menu, selecting "Get Info", and looking at the file path shown. If you have multiple music libraries in different locations, you'll need to define multiple volume mappings.

For Docker users, this path must match the container's /plex/music mount point. For CLI users running on a different machine than Plex, ensure the paths are identical through network shares or mapped drives.

Plex is treated as the primary source of truth due to technical limitations - neither Plex nor audio files maintain reliable timestamps for rating changes, making it impossible to determine which rating was set most recently.

The synchronization follows these rules:

1. If ratings match: No action needed
2. If ratings differ: Plex’s rating always wins
3. If only one has a rating:
   • Plex rating exists → Update file
   • File rating exists → Update Plex

This ensures your ratings stay consistent while working within the technical constraints of both systems.

The use of this source code is governed by an MIT-style license that can be found in the LICENSE file.