PlexSymlinker

This gem allows creating a Plex-friendly folder structure with symlinks for your audio books.
All you need are audio files with correct tagging, the gem takes care of making Plex understand them without you having to change the way you’re organising your files.

The Problem

Most of my audio files are in apple’s m4b format, leaving me with one file per book most of the times:

📁 audiobooks
 ∟ 📁 author name
    ∟ book1.m4b
    ∟ book2.m4b

The problem with this structure is that Plex’ music agent doesn’t quite understand it.
Even though the files are properly tagged with author, album, etc., Plex tends to create a giant album out of all the files inside - often with the first audio book as album name.

What the Plex music agent expects is a structure like this:

📁 audiobooks
 ∟ 📁 author name
    ∟ 📁 Book 1
       ∟ book1.m4b
    ∟ 📁 Book 2
       ∟ book2.m4b

This would mean that I’d have to introduce single-file-directories into my structure which didn’t really make sense for me - especially as I have a lot of “Hörspiele” (mostly german format of short audio books with multiple actors + music).

This gem’s solution

plex_symlinker creates symlinks pointing to your actual audio files in exactly the structure Plex’ music agent expects to find. It uses the embedded tags in your files to build it, so even one big directory with all your audio files in it would work as expected.

Just point plex to the symlink directory instead of your actual files and you’re good to go.

Installation

There are 2 ways to install/use this gem:

Option 1: Install the gem on your local machine and run it directly

bash gem install plex_symlinker

As this gem makes use of taglib-ruby, you have to make sure that the necessary packages are installed on your machine.
Please refer to robinst/taglib-ruby for more information.

Option 2: Use the docker image

A docker image is available which includes all necessary dependencies and can be used out-of-the-box by mounting the necessary directories.

Usage

Using the gem executable

0. Make sure your files are properly tagged!

At least the album and album artist fields have to set accordingly.

But since you are planning to import those files into Plex which needs a lot more information, it would make sense to fill out all details you can provide.

1. Run the gem executable with source and target directory

bash plex_symlinker /path/to/audiobooks /path/to/symlinks

💡 If you ran PlexSymlinker before, you can just re-run it on the same directory again. It will automatically sync the symlinks against the actual files and even delete no longer existing files.

2. Create a Plex library pointing to the symlink directory

Using the Docker image

Please refer to Docker Hub for instructions

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/stex/plex_symlinker. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the PlexSymlinker project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.