Rolling Pebble

Rolling Pebble is a local lyrics workstation for searching, editing, timing, organizing, and publishing LRC lyrics.

It gives you a browser-based interface backed by a local Python server. Your projects, audio, lyrics, runtime environments, and model caches stay on your machine. Auto Timing is powered by py-roller in an isolated runtime so large audio dependencies do not pollute the main app environment.

What It Does

• Import audio and lyrics from local files, LRCLIB, and supported online sources.
• Edit metadata and lyric text in a focused LRC editor.
• Synchronize timestamps manually when you want frame-level control.
• Auto-time lyrics with py-roller using isolated CPU/CUDA runtime profiles.
• Review and clean up projects, model caches, runtime environments, and app data.
• Publish prepared lyrics through LRCLIB workflows.
• Use multiple languages through the built-in i18n layer.

Typical Workflow

1. Create or import a project with an audio file.
2. Import lyrics from LRCLIB, a local file, or the editor.
3. Clean up the lyric text and metadata.
4. Use the Synchronizer for manual timing, or Auto Timing for py-roller based alignment.
5. Review the generated LRC, export it, or publish it through LRCLIB.

Install

macOS Desktop (Apple Silicon)

Download the v0.7.1 arm64 DMG from GitHub Releases, open it, and drag Rolling Pebble.app into Applications.

1. Open the app and go to Settings -> Auto Timing.
2. Leave the runtime profile on Auto, then click Create / Repair Runtime and wait for success.
3. Choose the transcriber model in the advanced settings and click Pre-download Model.

The app includes Python 3.12.15, but not py-roller, audio dependencies, or model caches. These are installed into your user data directory. Installation and downloads require network access; configure a model-download HTTP/SOCKS proxy in Settings when needed. Full processing may download a separate Demucs model on its first run.

Distribution limitation: the DMG is ad-hoc signed and is not Apple-notarized. macOS Gatekeeper may block first launch. Do not disable system-wide security protections. This build targets Apple Silicon, not Intel Macs; the declared binary minimum is macOS 11, but dependency compatibility on older macOS releases has not been exhaustively validated.

Command Line

The macOS arm64 desktop build includes standalone Python 3.12. It does not include py-roller, its audio dependencies, or model caches. Desktop users configure these from Settings; no separate Python or Homebrew installation is required. See DESKTOP.md for packaging and release-validation requirements.

For the command-line installation below, Rolling Pebble requires Python 3.10 or newer. Auto Timing additionally needs a Python 3.12 executable available on your system because the isolated py-roller runtime is built on Python 3.12.

Recommended install:

python -m venv rollingpebble-env
. rollingpebble-env/bin/activate
python -m pip install -U pip
python -m pip install rollingpebble
rollingpebble

On Windows PowerShell:

py -m venv rollingpebble-env
.\rollingpebble-env\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install rollingpebble
rollingpebble

Then open:

http://127.0.0.1:6789

First Run

Start Rolling Pebble:

rollingpebble

Then open:

http://127.0.0.1:6789

The default server binds to 127.0.0.1, so it is intended for local use.

Auto Timing

Auto Timing uses py-roller for lyric alignment. Rolling Pebble does not install Torch, Demucs, faster-whisper, or other heavy audio dependencies into the main app environment. Instead, it creates a separate runtime under the app data directory.

To set it up:

1. Open Settings -> Auto Timing -> Runtime.
2. Choose a runtime profile.
3. Click Create / Repair Runtime.
4. Installation runs a runtime check automatically; Check can run it again later.

Then download the selected model from Settings before running Auto Timing. Environment installation and model downloads require network access. Runtime repairs keep model caches separate from the environment.

For command-line installations, if Python 3.12 is not detected automatically, set:

export LRC_ROLLER_RUNTIME_PYTHON=/path/to/python3.12

The current supported py-roller range is:

py-roller>=0.9.0,<0.10

Storage and Privacy

Rolling Pebble is local-first. It stores data under the user data directory, for example:

~/.local/share/rollingpebble

Inside the app, Settings -> Storage & Cleanup shows project data, model caches, runtime environments, and other app data. Model caches are stored separately from runtime environments so they can be reused across runtime repairs.

Rolling Pebble only contacts external services when you use features that need them, such as LRCLIB lookup/publishing, supported online source import, or model downloads for Auto Timing.

Developer Notes

For source development:

python -m venv .venv
. .venv/bin/activate
python -m pip install -U pip setuptools wheel
python -m pip install -e .
pnpm install

Run the backend and frontend together:

. .venv/bin/activate
rollingpebble dev

Or use two terminals:

# terminal 1
. .venv/bin/activate
rollingpebble serve --reload

# terminal 2
pnpm dev

Release packaging details live in RELEASE.md.