Skip to main content

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.

Latest release Supported Python versions Requires FFmpeg MIT License Code style: black

Installation | CLI Usage | API Usage

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:

  1. Output option file extension (--output example.wav)
  2. Explicit input file type (--format ogg)
  3. 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

nightcore-1.1.0.tar.gz (9.2 kB view details)

Uploaded Source

Built Distribution

nightcore-1.1.0-py3-none-any.whl (9.9 kB view details)

Uploaded Python 3

File details

Details for the file nightcore-1.1.0.tar.gz.

File metadata

  • Download URL: nightcore-1.1.0.tar.gz
  • Upload date:
  • Size: 9.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.0.0b2 CPython/3.8.0 Darwin/19.0.0

File hashes

Hashes for nightcore-1.1.0.tar.gz
Algorithm Hash digest
SHA256 cf4e04c0c8c1a039efefc051411495efa1e0bac085b6c1f6bee8b49053823cd1
MD5 71cf641ae802ec20dd8fa3b631384656
BLAKE2b-256 493b227ce394961ccc3b7a72f5b0cded6a106eed683a71579ea03d4873d51148

See more details on using hashes here.

File details

Details for the file nightcore-1.1.0-py3-none-any.whl.

File metadata

  • Download URL: nightcore-1.1.0-py3-none-any.whl
  • Upload date:
  • Size: 9.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.0.0b2 CPython/3.8.0 Darwin/19.0.0

File hashes

Hashes for nightcore-1.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 8a8c2097af4b13fe981cf3f0f18e7169be0c3a11bc5f0301186e15d9ec5655c9
MD5 7045591d88cdc334fc8126f273b56132
BLAKE2b-256 204dfc97e2fffa1bd3874b3a9e81108378e6a07fd665e62ee56f052b179b49c7

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page