ReDub

A terminal-based karaoke tool that removes vocals from an MP3, displays timed lyrics from an .lrc file, records your microphone while the instrumental plays, then overlays your recording onto the accompaniment and exports an MP3.

What it does

1. Pick a song from a numbered list
2. Runs Spleeter to generate an instrumental (accompaniment.wav)
3. Plays the instrumental while:
   • showing lyrics from an .lrc file in sync
   • recording your mic audio
4. Mixes your mic recording over the accompaniment
5. Saves the final result as an MP3

Requirements

• Python 3.x
• ffmpeg available on PATH
• Spleeter installed and working (spleeter separate ...)
• Working microphone input device
• MP3 files + matching LRC lyric files

Folder Setup

Your project expects these folders:

• mp3/ — your .mp3 songs
• lrc/ — your .lrc lyric files
• output_folder/ — created by Spleeter (instrumental output)
• my_recordings_temp/ — temporary WAV recordings (created at runtime)
• my_recordings/ — final mixed MP3 output (created at runtime)

If some output folders don’t exist yet, create them:

mkdir -p my_recordings my_recordings_temp output_folder

File Naming Rules (Important)

For a song to work, the .mp3 and .lrc must have the exact same base filename.

Example:

• mp3/Artist - Song Title.mp3
• lrc/Artist - Song Title.lrc

If the filenames don’t match exactly (same punctuation, spacing, etc.) the lyrics won’t load for the selected track.

Filename format

This app expects the track name to follow this pattern:

Artist - Title

So the file should look like:

Artist - Title.mp3
Artist - Title.lrc

Install

1) Create and activate a virtual environment

python -m venv venv
source venv/bin/activate

2) Install Python dependencies

pip install -U pip
pip install pydub sounddevice soundfile colorama pyfiglet numpy

(If you have a requirements file, use pip install -r requirements.txt instead.)

3) Install system dependencies

You need ffmpeg installed and available on your PATH.

You also need Spleeter available via the spleeter command.

Required Manual Venv Edit (Important)

To make this project work cleanly, you need to modify a file inside your virtual environment after installing dependencies.

Edit this file:

venv/lib/python3.xx/site-packages/pydub/playback.py

Replace xx with your Python minor version (example: python3.10 for Python 3.10).

What to change

Find the function:

_play_with_ffplay

Then add the following code below the function definition (as a new function):

import os
def _play_with_ffplay_suppress(seg):
    with NamedTemporaryFile("w+b", suffix=".wav", delete=False) as f:
        PLAYER = get_player_name()
        seg.export(f.name, "wav")
        devnull = open(os.devnull, 'w')
        subprocess.call([PLAYER,"-nodisp", "-autoexit", "-hide_banner", f.name],stdout=devnull, stderr=devnull)

This suppresses ffplay output spam while the audio plays.

Run

Put your songs in mp3/ and matching lyrics in lrc/, then run:

python karaoke.py

You’ll get a menu of available tracks. Pick a number, then sing.

Output

• Temporary mic recordings are written to: my_recordings_temp/
• Final mixed MP3 files are written to: my_recordings/

Notes / Troubleshooting

• If Spleeter hasn’t been run for a song yet, it will generate:

  output_folder/<song_name>/accompaniment.wav
  

• If you don’t hear your mic monitoring, check your OS sound input/output device settings.
• If you get errors about audio devices, sounddevice is usually complaining about a missing default device or mismatched channel setup.