syncfm-core

syncfm-core is a reusable Python 3.12 synchronization engine and command-line application for copying missing scrobbles between Last.fm, Libre.fm, and GNU.fm-compatible services.

It does not blindly copy a complete library. For a selected, inclusive Unix-timestamp range it:

downloads source and target scrobble snapshots;
compares exact (artist, title, timestamp) identities;
queues events present at the source and absent at the target;
enriches those events with source-side MusicBrainz ID and duration data;
submits them to the target in chronological order; and
stores enough SQLite state to resume safely after an interruption.

Project status: version 0.1.0 is marked pre-alpha. Pin a revision when embedding it in another project and test the behavior against your chosen networks.

Start here

Getting Started — install the CLI and complete a first sync.
Profiles and Credentials — configure Last.fm, Libre.fm, GNU.fm, keyring storage, and proxies.
CLI Reference — every command, option, and environment variable.
Using syncfm-core in Python — embed the engine in another application.
Public API Reference — exported factories, models, methods, protocols, and exceptions.

Understand the engine

Synchronization Behavior — ranges, comparison identity, metadata, ordering, retries, and progress.
Persistence and Recovery — sessions, SQLite state, resume, reconciliation, and discard.
Networks and Proxies — supported backends, authentication, GNU.fm hostnames, and proxy syntax.
Troubleshooting — common errors and corrective actions.
Development — source checkout, quality checks, architecture, and contribution notes.

Important properties

Property	Behavior
Direction	One-way: source to target
Time range	Inclusive start and end Unix timestamps
Default start	Target's latest scrobble timestamp
Default end	Current Unix time
Match key	Artist, title, and timestamp; album is ignored
Processing	Synchronous and sequential
Retry default	3 attempts, 5 seconds between transient failures
State	Local SQLite database
Profile config	Versioned TOML document
Secrets	OS keyring by default; TOML opt-in available
License	GNU General Public License v3.0 or later

Projects embedding or distributing the package should review the GPL-3.0-or-later obligations described in Using syncfm-core in Python.

The source repository is git.hirad.it/Hirad/syncfm-core.