Metadata-Version: 2.4
Name: rollingpebble
Version: 0.9.2
Summary: Local lyrics workstation for editing, timing, translation, and publishing.
Author: Harmonese
License-Expression: MIT
Project-URL: Homepage, https://github.com/Harmonese/rollingpebble
Project-URL: Repository, https://github.com/Harmonese/rollingpebble
Project-URL: Issues, https://github.com/Harmonese/rollingpebble/issues
Project-URL: Changelog, https://github.com/Harmonese/rollingpebble/blob/main/CHANGELOG.md
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.27
Requires-Dist: keyring<26,>=25
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.27
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: pylrclib-cli>=0.4.6
Provides-Extra: roller
Provides-Extra: full
Provides-Extra: dev
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/Harmonese/rollingpebble/main/frontend/public/favicons/apple-touch-icon.png" alt="Rolling Pebble" width="120" height="120">
</p>

# Rolling Pebble

[![PyPI](https://img.shields.io/pypi/v/rollingpebble.svg)](https://pypi.org/project/rollingpebble/)
[![Python](https://img.shields.io/badge/python-3.10%2B-3776AB.svg)](https://www.python.org/downloads/)

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

It provides a Tauri desktop app for macOS Apple Silicon, Linux x86_64 and Windows x64 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)** with py-roller 0.10.3, then review an independent editable preview before applying it.
- **Translate** through a local or cloud OpenAI-compatible service, with synchronized bilingual LRC editors.
- **Save and recover** projects automatically after their first save, including translations and audio changes.
- **Manage storage** for projects, models, results and temporary data in one application directory.
- **Publish** prepared lyrics through LRCLIB workflows.
- **Use multiple languages** through the built-in i18n layer.

Version 0.9.2 fixes project-arrow navigation so opening or saving a project no longer traps navigation between two projects. It also updates the default literary translation prompt. Existing saved prompts are preserved; use Reset Prompt and save the connection to adopt the new default. Desktop installers are available for macOS Apple Silicon, Linux x86_64 and Windows x64.

## 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 establishes a project; later edits save automatically. Auto Timing also saves the workspace before processing.
5. Review Auto Timing results in Auto Timing Review. Apply updates the workspace and follows normal autosave. Export LRC or publish through LRCLIB.

The Project panel shows **Unsaved**, **Saving**, **Saved**, or **Save failed**. Save Project or Ctrl/⌘+S saves immediately. Replacing local audio preserves lyrics, timestamps and marks. Importing lyrics preserves existing metadata unless the imported file supplies replacements. Existing projects save automatically, uploading audio only when it changes. A single recovery workspace preserves unfinished text, translations and pending audio without adding a project to the list; startup offers recovery after an interruption. Desktop exit waits for saves or an explicit discard.

## Install

### macOS Desktop (Apple Silicon)

Download an arm64 DMG from [GitHub Releases](https://github.com/Harmonese/rollingpebble/releases), open it, and drag **Rolling Pebble.app** into **Applications**.

1. Open the app; the unified startup screen prepares or checks bundled components.
2. On first use, choose English, Mandarin and/or multilingual models; Whisper large-v3 and Demucs are shared. ModelScope is the default source; official downloads and HTTP(S) proxy settings are also available.
3. Subsequent launches verify installed weights and offer targeted download or repair for selected missing models or damaged installed models. Choose Later to enter the workspace without downloading.

The app bundles Python 3.12.15, FFmpeg and hashed binary wheels for py-roller 0.10.3 and its dependencies. Runtime installation is offline and needs no compiler or Homebrew. Model weights are downloaded separately through startup setup or Settings. HTTP(S) proxies are supported; SOCKS proxies are not. Auto Timing defaults to offline operation.

**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 with macOS 14 or newer.

### Linux Desktop (x86_64)

Download the `.deb` or `.AppImage` and its `SHA256SUMS` from [GitHub Releases](https://github.com/Harmonese/rollingpebble/releases). Ubuntu 24.04 x86_64 is the supported baseline; other distributions and older systems require separate validation.

- **Debian package:** install with `sudo apt install ./<package>.deb` so system dependencies are resolved.
- **AppImage:** make it executable and run it. If FUSE is unavailable, use `./<package>.AppImage --appimage-extract-and-run`.

### Windows Desktop (x64)

Download the x64 `setup.exe` and its `SHA256SUMS` from [GitHub Releases](https://github.com/Harmonese/rollingpebble/releases). Run the installer to install for the current user; administrator rights are not required for the app installation.

Requires Windows 10 version 1903 or newer, or Windows 11, and Microsoft Edge WebView2. The installer can download WebView2 if it is missing, which requires network access. The installer is unsigned, so Windows may show an unrecognized-app warning. Windows ARM64 is not a supported native target.

All three desktop packages include Python, offline engine dependencies, FFmpeg and eSpeak. Models are downloaded separately in the app. Linux and Windows engine packages use CPU dependencies; CUDA is not included.

### Verify Downloads

Compare the installer's SHA-256 with the accompanying `SHA256SUMS` before installing:

```bash
# macOS
shasum -a 256 "<installer>.dmg"
# Linux
sha256sum -c SHA256SUMS
```

```powershell
# Windows PowerShell
Get-FileHash '.\<installer>.exe' -Algorithm SHA256
```

Checksums verify file integrity; they are separate from platform code signing.

### Command Line

The Python distribution includes the backend and WebUI, but not the platform-specific engine wheelhouse, standalone Python or FFmpeg. Manual editing works independently. For the supported Auto Timing installation use a prepared desktop app, or prepare the matching engine resources from a source checkout as described in [desktop packaging](docs/DESKTOP.md).

For the command-line installation below, Rolling Pebble requires Python 3.10 or newer. Auto Timing requires the matching bundled Python 3.12 and engine resources; it does not fall back to system Python.

Recommended install:

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

On Windows PowerShell:

```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:

```text
http://127.0.0.1:6789
```

## Auto Timing

Auto Timing uses Protocol v2 for line-level alignment. Language defaults to Auto for new and upgraded installations; it selects English, Mandarin, mixed Mandarin/English or the general multilingual phoneme backend from lyric text. Mandarin does not imply Cantonese; Mandarin, mixed and multilingual singing alignment remain experimental. Ordered follows complete input lyrics, including every repeat, and retains unresolved lines for manual timing. Unordered discovers sung occurrences, including repetitions absent from the input. CTC refines timing. New installations default to Ordered; existing settings retain Unordered. Results can still miss or misplace lines and require review. Heavy dependencies stay in a separate runtime under the app data directory.

To set it up:

1. Launch the desktop app. The unified startup screen prepares or checks bundled components, then verifies installed models and offers setup or repair before opening the workspace.
2. Download the required models explicitly.
3. If preparation fails, use **Repair**. Version and logs are available in the collapsed **Diagnostics** section.

Preparation is offline and shared between startup, Settings and Start. Failed startup checks offer Repair or Continue for manual editing. Closing Settings does not cancel it. Cancelling a pending Start cancels only the intent to run; changing the workspace or options while waiting also prevents automatic start.

Prepare the fixed models before starting. Original is the default audio source; Vocals is an explicit choice. CTC supports Auto/CPU/MPS; Whisper and Demucs run on CPU. Runtime readiness and model readiness are separate. English, Mandarin and multilingual CTC models are managed separately. The eSpeak pronunciation library and data are bundled for multilingual alignment. No CUDA, Full/Quick or research-algorithm switches are exposed.

Auto Timing Review follows engine revisions until the first text or timing edit, then retains an independent autosaved draft. Use Latest discards edits after confirmation. Apply updates the workspace and triggers normal autosave for an existing project. Failed or cancelled runs with content can be applied as Partial after confirmation. Batch runs are serial and each result is reviewed separately.

The current supported py-roller range is:

```text
py-roller>=0.10.3,<0.11, protocol 2 (desktop pinned to 0.10.3)
```

## Translation

Configure a local or cloud OpenAI-compatible connection in Settings, then use the Editor translation tool for whole-song translation, single-line retranslation and manual correction. The English default prompt emphasizes concise lyric phrasing, imagery, wordplay and semantic accuracy; it does not change with the interface language. Saved prompts are preserved across upgrades. Use Reset Prompt and save the connection to adopt the new default. Line-ID mapping and JSON output rules are enforced separately by the application.

## Storage and Privacy

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

```text
~/.local/share/rollingpebble
```

Inside the app, **Settings -> Storage** manages the application location and shows Projects, Models, Results, Cache and Components. Model controls live in **Auto Timing** settings. Runtime components are managed automatically; repairing them preserves models and projects. A separate recovery area retains the current unfinished workspace and is protected from ordinary cache cleanup.

Rolling Pebble contacts external services for LRCLIB lookup/publishing, online imports, model downloads, and configured Translation requests. Translation sends lyric text and title/artist/album to your chosen service, never audio or file paths. API keys use the system credential store, with explicit session-only fallback when unavailable. Local model services can keep translation on your own machine.

## Documentation

- [User guide / 使用指南](docs/USER_GUIDE.md): temporary workspaces, saving, timing, shortcuts, export and deletion.
- [Storage and cleanup](docs/STORAGE.md): storage roots and the exact automatic-deletion behavior.
- [Documentation index](docs/README.md) and [changelog](CHANGELOG.md).

For contributors: [development](docs/DEVELOPMENT.md), [architecture](docs/ARCHITECTURE.md), [desktop packaging](docs/DESKTOP.md) and [release checklist](docs/RELEASE.md).

The editor originated from [LRC Maker](https://github.com/magic-akari/lrc-maker); its [MIT copyright notice](frontend/LICENSE) is preserved.
