A FUSE filesystem that splits FLAC+CUE files into individual tracks
trackfs
trackfs
is a read-only FUSE filesystem that splits audio files that contain full albums into individual FLAC files per track.
trackfs
supports three flavors of album files:
Accompanying cuesheets must use the fileextension .cue
and have the same basename as album file.
The recommended way to use trackfs
is using the docker image andresch/trackfs
. In case you want to use trackfs
without docker see section Manual Installation below.
You can directly run trackfs
on any Linux system with Docker and FUSE installed.
The simplest way to get familiar with trackfs
is to just launch it from the command-line:
docker run --rm \
--name=trackfs \
--device /dev/fuse \
--cap-add SYS_ADMIN \
--security-opt apparmor:unconfined \
-v /path/to/yourmusiclibrary:/src:ro \
-v /path/to/yourmountpoint:/dst:rshared \
andresch/trackfs \
--root-allowed
Replace /path/to/yourmusiclibrary
with the root directory where trackfs
scans for your album files and /path/to/yourmountpoint
with the directory that you want to use as mount point for the trackfs
-filesystem. Ideally the mount point already exists, if not, docker will create the directory (but then with root as owner)
Once started you will find all directories and files from your music library also in the trackfs
-filesystem. Only album files got replaced: Instead of a single album file you will find individual FLAC files for each track found in the cue sheet. The track-files will have the following names:
{album-file}.#-#.{tracknumber}.{track-title}.flac
While the tracks can be used like regular files, they don't exist in the physical file system on your machine. Instead trackfs
creates them on the fly whenever an application starts loading any of the track files. This usually takes (depending on your system) a few seconds.
In case you're not familiar with docker, a quick explanation on the used docker arguments:
-v /path/to/yourmusiclibrary:/src:ro
: make your music library accessible for trackfs by mounting it to /src in read-only mode inside your docker container-v /path/to/yourmountpoint:/dst:rshared
: share the trackfs filesystem (/dst
inside the container) accessible under your mount pointandresch/trackfs
: the name of the trackfs
docker image on docker hub.--device
, --cap-add
--security-opt
: With those arguments you grant the docker container the privileges required to mount FUSE filesystems. You can try to leave out the --security-opt
option as it is not required on all systems. There is onging discussion if docker containers should allow mounting FUSE filesystems, by just using the --device
option, but for now this is not the case.--rm
: remove the orphaned container after terminationPlease refer to the docker run documentation for more details.
trackfs
as regular userWhile the above is working just fine, it is not the recommended way to use trackfs
as it runs trackfs
inside the docker container as user root. Running as root does allow trackfs
to access any file in your music library, irrespective of its underlying file permissions. If we would have omitted the --root-allowed
argument, trackfs
would have terminated with a corresponding error message.
Instead it is recommended to let trackfs
run as a regular user. For that to work we need a few changes:
Make sure that in your host system the file /etc/fuse.conf
has the option user_allow_other
enabled, e.g. by calling from your command line
sudo echo "user_allow_other" >> /etc/fuse.conf
Make sure that your mount point already exists and is owned by the user that is supposed to run trackfs
.
Use the docker run option --user
to define the user that will run trackfs
E.g. the following docker command would run trackfs
with the current user:
docker run --rm \
--name=trackfs \
--device /dev/fuse \
--cap-add SYS_ADMIN \
--security-opt apparmor:unconfined \
--user $(id -u):$(id -g) \
-v /path/to/yourmusiclibrary:/src:ro \
-v /path/to/yourmountpoint:/dst:rshared \
andresch/trackfs
trackfs
optionstrackfs
provides a few options that allow you to tweak its default behavior:
-e EXTENSION
, --extension EXTENSION
(default: "(\.flac|\.wav)") :
A regular expression matching file extension of album files in the music library-s SEPARATOR
, --separator SEPARATOR
(default: ".#-#."):
The separator used inside the name of the track-files. Must never occur in regular filenames-i IGNORE
, --ignore-tags IGNORE
(default: "CUE_TRACK.*|COMMENT"):
A regular expression matching all tags in the FLAC+CUE file that will not be copied over to the track FLACs-k
, --keep-album
:
Keep the source album file (FLAC+CUE or WAVE) in the trackfs
filesystem in addition to the individual tracks-t TITLE_LENGTH
, --title-length TITLE_LENGTH
(default: 20):
Nr. of characters of the track title in filename of track--root-allowed
:
Allow running trackfs
as with root permissions; Neither necessary nor recommended.
Use only when you know what you are doing-v
, --verbose
:
Activate info-level logging-d
, --debug
:
Activate debug-level loggingYou can use -h
, --help
to get a list of all all options. Keep in mind that the parameters root
and mount
are already defined with the two -v
options to docker run
and are implicitly set by the docker container.
Most tags of the album file will be set in the track files too. There are only two exceptions:
CUESHEET
-tag)--ignore-tags
option (default: "CUE_TRACK.*|COMMENT"
)In addition trackfs
does the following modifications to tags:
ARTIST
tag but no ALBUMARTIST
tag, then an ALBUMARTIST
tag will be created with the value of ARTIST
tag.TITLE
tag, but no ALBUM
tag, then an ALBUM
tag will be created with the value of the TITLE
tag.TITLE
tag for a given track, it overwrites the TITLE
tag from the album filePERFORMER
tag for a given track, it overwrites the ARTIST
tag from the album fileSONGWRITER
tag for a given track, it overwrites the COMPOSER
tag from the album fileCue sheet entries of type PERFORMER
, SONGWRITER
will be split at ";" characters and create multiple tags in the track file.
In case the album has embedded pictures, the first picture will be available in the track file. Alternatively trackfs
will scan the directory for a jpg-file with the same basename as the album file or a file named folder.jpg
In case you want/have to run trackfs
on some linux system without docker you can also install the python package trackfs
manually. Please refer to the homepage of the trackfs python package for further information.
trackfs
is currently in an early stage. While it runs stable on the author's NAS, it has not been tested in other environments, esp. on various Linux distributions with different kernels/FUSE versions. Using the dockerized version should remove some of the difficulties, but given the dependencies on FUSE, some my still remain.
Also keep in mind that this is the author's first python project, so don't expect that the source code matches professional quality criteria of experienced python coders.
There are a few ideas for additional improvements
When trackfs
doesn't get properly terminated, then your system might still have an orphaned mount point. When you then restart trackfs
this will fail with a corresponding error message.
In that case you have to first unmount the orphaned mount point by calling:
sudo umount /path/to/yourmountpoint
In case the path to your mountpoint contains a symbolic link the above might not work as umount
expects the real path of the mount point. In that case use
mount -t fuse
to find the path that umount
expects.
In case trackfs
hangs (should not happen, but just in case) you might have to explicitly kill it. For that we use the docker stop
command (which give the container a chance to currently shutdown before killing it). This requires the container name or container id as parameter.
If you have defined a container name (e.g. to "trackfs") you can just use
docker stop trackfs
otherwise your first have to find the id of the container that runs the andresch/trackfs image:
docker stop $(docker ps | awk '/andresch\/trackfs/{print $1}')
trackfs
began its live as a clone of FLACCue. While FLACCue is designed for the usage with the Plex media server, the underlying idea of both projects is the same. Although there is little unmodified code of FLACCue left in trackfs
, the project would most likely not have been started without the ideas in this groundwork. Kudos go to acenkos!
trackfs
is licensed under the terms of the GNU Lesser General Public License v3.0