Rolling Pebble

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

It provides a Tauri desktop app for macOS Apple Silicon and a browser 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.
• Repeat lyrics with numbered marks, playback-time insertion and undo.
• Auto-time (Experimental) 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. Open an audio file in a temporary workspace; importing does not create a project.
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 and export directly. Save Project keeps your audio and lyrics; Auto Timing also saves the workspace before processing.
5. Review the generated LRC, export it, or publish it through LRCLIB.

The Project panel shows Saved or Unsaved. Replacing local audio preserves lyrics, timestamps and marks. Importing lyrics preserves existing metadata unless the imported file supplies replacements. Save Project updates the same project, uploading audio only when it changes.

Install

macOS Desktop (Apple Silicon)

Download an arm64 DMG from GitHub Releases, open it, and drag Rolling Pebble.app into Applications. This checkout prepares version 0.7.4.

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 packaging 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

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.

Documentation

• User guide / 使用指南: temporary workspaces, saving, timing, shortcuts, export and deletion.
• Storage and cleanup: storage roots and the exact automatic-deletion behavior.
• Development and architecture.
• Desktop packaging and release checklist.
• Documentation index and changelog.