Intuitive CLI and API for modifying the speed/pitch of audio
Project description
Nightcore - Easily modify speed/pitch
A focused CLI and API for changing the pitch and speed of audio. Requires FFmpeg.
I had the idea for this a long time ago, and wanted to make it to prove a point. This program is not intended for, nor should it be used for, copyright infringement and piracy. Nightcore is not, and has never been, fair use.
Installation
FFmpeg is a required dependency - see here for instructions on how to set it up!
With FFmpeg installed, you can use pip
to install nightcore
(although pipx is recommended when only installing the CLI)
pip install nightcore
Building from source
nightcore
is built using Poetry.
$ git clone https://github.com/SeparateRecords/nightcore
$ poetry install
$ poetry build
CLI Usage
nightcore
is predictable and ensures there is no unexpected behaviour. As nightcore relies on FFmpeg under the hood, any format supported by FFmpeg is supported by the CLI.
Speed/pitch
Speeding up a track is super easy. By default, it will increase the pitch by 1 tone.
$ nightcore music.mp3 > out.mp3
You can manually set the speed increase by passing a number after the file. Without specifying a type, the increase will be in semitones.
$ nightcore music.mp3 +3 > out.mp3
Types
You can change the type of speed increase by providing it after the number. At the moment, nightcore can take any of semitones
, tones
, octaves
or percent
.
$ nightcore music.mp3 +3 tones > out.mp3
When using percentages, 100 percent
means no change, 150 percent
is 1.5x speed, 80 percent
is 0.8x speed, etc.
$ nightcore music.mp3 150 percent > out.mp3
Format & Codec
If file's format cannot be inferred from its extension, you can specify it manually with --format
(-f
).
$ nightcore --format ogg badly_named_file > out.mp3
The codec can be manually set using --codec
(-c
).
Output
If the output cannot be redirected, you can specify an output file with --output
(-o
). The format will be guessed from the extension.
$ nightcore music.mp3 --output out.mp3
To manually set the output format (useful if redirecting), use --output-format
(-x
).
$ nightcore music.mp3 --output-format ogg > music_nc.ogg
If this option is not provided, the output format will be guessed in this order, defaulting to MP3 if all fail:
- Output option file extension (
--output example.wav
) - Explicit input file type (
--format ogg
) - Input file extension (
music.ogg
)
EQ
To compensate for a pitch increase, the output track will have a default +2db bass boost and -1db treble reduction applied. To disable this, pass in --no-eq
. Note that if the speed is decreased, there will be no automatic EQ.
$ nightcore music.mp3 --no-eq > out.mp3
API Usage
The nightcore API is built using pydub, a high level audio processing library. It's worth reading a bit of its documentation (or at least the section on exporting), but you'll get by with only having read the examples below.
The API itself performs no equalization, unlike the CLI - see nightcore/cli.py for the implementation (search "parameters").
As the word nightcore
is long, it's recommended to import the module as nc
.
Quickstart
You can use any of Octaves
, Tones
, Semitones
, or Percent
to change speed. These are all subclasses of the base RelativeChange
class.
Using the @ operator with one of the above classes is the most convenient way to nightcore a path-like object or AudioSegment
.
import nightcore as nc
nc_audio = "tests/test.mp3" @ nc.Tones(1)
nc_audio.export("tests/test_nc.mp3")
Advanced Usage
nightcore(audio_or_path, amount, **kwargs) -> AudioSegment
The @ operator is shorthand for the nightcore
function. The function only needs to be called manually if:
- You need to provide additional keyword arguments to
AudioSegment.from_file
- The operator is less readable in context
- You need to use a function
There is also an equivalent async function in its own namespace (nightcore.aio
).
import nightcore as nc
# Additional keyword args are passed to AudioSegment.from_file
audio = nc.nightcore("/tmp/badly_named_audio", nc.Semitones(2), format="ogg")
Contributing
Contributions, feedback, and feature requests are all welcome and greatly appreciated, no matter how small.
License
This project is licensed under the MIT license.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for nightcore-1.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8a8c2097af4b13fe981cf3f0f18e7169be0c3a11bc5f0301186e15d9ec5655c9 |
|
MD5 | 7045591d88cdc334fc8126f273b56132 |
|
BLAKE2b-256 | 204dfc97e2fffa1bd3874b3a9e81108378e6a07fd665e62ee56f052b179b49c7 |