pymusiclooper 2.0.0

Automatically find loop points of any song export into intro/loop/outro sections or loop points, with optional playback through the terminal.

PyMusicLooper

A python script for repeating music seamlessly and endlessly, by automatically finding the best loop points.

Features:

• Find loop points within any music file (if they exist).
• Supports a large set of different audio formats, and all the popular ones (MP3, OGG, M4A, FLAC, WAV, etc).
• Play the music file endlessly and seamlessly with the best discovered loop.
• Export to intro/loop/outro sections for editing or seamless playback within any music player that supports gapless playback.
• Export loop points in samples to a text file (e.g. for use in creating custom themes with seamlessly looping audio).

Installation

Pre-requisites

• Python >= 3.6
• ffmpeg (adds support for MP3 and other proprietary audio formats)

Installation Options

Base Install

Base installation (can export intro/loop/outro sections to WAV, or the loop points to a text file; easiest to install):

pip install git+https://github.com/arkrow/PyMusicLooper.git

Complete Install

Complete installation adds tag preservation and terminal playback support (requires additional setup):

pip install git+https://github.com/arkrow/PyMusicLooper.git#egg=pymusiclooper[complete]

Additional requirements for "complete" feature set:

• pytaglib for tag preservation (see pytaglib's installation notes)
• mpg123 to play music endlessly through the terminal.

Usage

usage: python -m pymusiclooper [-h] [-v] [-i] [-p] [-e] [--preserve-tags] [-j]
                               [-t] [-r] [-f] [-n N_JOBS] [-o OUTPUT_DIR]
                               [-m MIN_DURATION_MULTIPLIER]
                               path

A script for repeating music seamlessly and endlessly, by automatically
finding the best loop points.

positional arguments:
  path                  path to file or directory

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         enable verbose logging output
  -i, --interactive     manually preview/choose which loop to use out of the
                        discovered loop points

Play:
  -p, --play            play the song on repeat with the best discovered loop
                        point (default).

Export:
  -e, --export          export the song into intro, loop and outro files (WAV
                        format).
  --preserve-tags       export with the track's original tags.
  -j, --json            export the loop points (in samples) to a JSON file in
                        the song's directory.
  -t, --txt             export the loop points in samples to a loop.txt file
                        (compatible with LoopingAudioConverter).
  -r, --recursive       process directories and their contents recursively
                        (has an effect only if the given path is a directory).
  -f, --flatten         flatten the output directory structure instead of
                        preserving it when using the --recursive flag.
  -n N_JOBS, --n-jobs N_JOBS
                        number of files to batch process at a time (default:
                        1). WARNING: greater values result in higher memory
                        consumption.

General Options:
  -o OUTPUT_DIR, --output-dir OUTPUT_DIR
                        specify a different output directory.
  -m MIN_DURATION_MULTIPLIER, --min-duration-multiplier MIN_DURATION_MULTIPLIER
                        specify minimum loop duration as a multiplier of song
                        duration (default: 0.35)

PyMusicLooper will find the best loop point it can detect, and will then, depending on your arguments:

(a) play the song on repeat using the best discovered loop point (default, requires mpg123);

(b) export intro/loop/outro sections of the song (currently outputs as WAV-only; however you may convert them with ffmpeg or Audacity);

(c) export the loop points (in samples) to a JSON or text file compatible with LoopingAudioConverter, which you can use for audio loops in custom theme creation, game engine audio loops, etc.

Note: using the interactive -i option is highly recommended, since the algorithmically chosen "best" loop point may not be perceptually good, due to loudness difference, overall song beat, etc.

Example Usage

Side note: Most terminals support file drag-and-drop, which can be utilized instead of manual path navigation/selection.

Play

Play the song on repeat with the best discovered loop point.

python -m pymusiclooper "TRACK_NAME.mp3"

Export

Export the song into intro, loop and outro files, and carry over the track's original tags.

python -m pymusiclooper -e "TRACK_NAME.ogg" --preserve-tags

Export the loop points of all the songs in a particular directory to a single loop.txt file (compatible with LoopingAudioConverter).

python -m pymusiclooper -t "/path/to/dir/"

Note: each line in loop.txt follows the following format: {loop-start} {loop-end} {filename}

Miscellaneous

If the loop is very long (or very short), you may specify a different minimum duration for the algorithm to use, which is 0.35 (35%) by default. If the most of the track is the loop section, specifying a higher multiplier will also speed the algorithm up. Here -m 0.85 means that, excluding silence, the loop section is at least 85% of the music track.

python -m pymusiclooper "TRACK_NAME.flac" -m 0.85

Loop points can be chosen and previewed interactively before playback/export using the -i flag, e.g.

python -m pymusiclooper "TRACK_NAME.wav" -e -i

Example of multiple functionalities in action

Export intro/loop/outro sections and loop points of all the songs (both json and as loop.txt) in the current directory and its subdirectories, to a folder called "Music Loops", processing 4 tracks concurrently, preserving the original tags.

python -m pymusiclooper -rejt . -o "Music Loops" -n 4 --preserve-tags

Building from source

Required python packages: pip and setuptools.

Clone the git repository to a directory of your choice and cd to inside the repo.

Run:

python setup.py build

Followed by:

python setup.py install

Contribution

If there is a song that you think PyMusicLooper should be able to loop but doesn't, please feel free to open an issue with a link to that song and mention the approximate timestamp at which it loops. Forks and pull requests are of course welcome.

Acknowledgement

This project started out as a fork of Nolan Nicholson's project Looper. Although at this point only a few lines of code remain from that project due to adopting a completely different approach and implementation; this project would not have been possible without their initial contribution.

Version History

Note: all versions released prior to v2.0 are considered unstable experimental releases.

• v1.7.0 Added an option to export a loop.txt file compatible with LoopingAudioConverter and a flatten option if the new directory behavior introduced in v1.6.2 is not desired. Fixed a bug with non-recursive batch export.
• v1.6.2 Preserve source directory tree structure in batch output directory. Fixed json export bug.
• v1.6.1 Lowered note similarity threshold to improve loop point quality
• v1.6.0 Added interactive option for user loop selection
• v1.5.1 Fixed issues caused by previous release's refactoring
• v1.5.0 Batch mode now implicitly enabled based on given path
• v1.4.0 Major improvements to the loop detection algorithm; added option to preserve tags
• v1.3.2 Fixed fallback PLP method not working sometimes
• v1.3.1 Fixed batch processing mode selection
• v1.3.0 Added multiprocessing support and progress bar for batch export
• v1.2.1 Save export output to a "looper_output" folder in the current working directory by default
• v1.2.0 Removed unreliable cache implementation
• v1.1.0 Added support for batch processing
• v1.0.0 Initial Release