Hirad/syncfm-core
Watch
1
0
Fork
You've already forked syncfm-core
 0
generated from Hirad/Template
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions
Page: Networks and Proxies
Pages
CLI Reference Development Getting Started Home Networks and Proxies Persistence and Recovery Profiles and Credentials Public API Reference Python Integration Synchronization Behavior Troubleshooting
1 Networks and Proxies
Hirad edited this page 2026-08-14 09:18:17 +03:30
Table of contents

Networks and Proxies

Built-in integrations use pylast behind SyncFM's MusicNetwork protocol.

Supported network types

Type Implementation Extra setting
lastfm pylast.LastFMNetwork None
librefm pylast.LibreFMNetwork None
gnufm Custom pylast._Network configuration hostname required

Every built-in network requires a non-empty username, API key, API secret, and either password or session key.

The adapter's stored/display name combines the service name and username, for example Last.fm Network [alice]. This identity is used to prevent resuming a session with the wrong account or direction.

GNU.fm-compatible instances

Create a profile with a bare hostname:

syncfm profile add community \
  --type gnufm \
  --hostname music.example.org \
  --username alice \
  --api-key PUBLIC_KEY

The hostname is lowercased and must not contain a URL scheme, path, @, or whitespace. Use music.example.org, not https://music.example.org/.

The adapter assumes HTTPS, a web-service endpoint at /2.0/, and GNU.fm-compatible API behavior.

Proxy configuration

Set a proxy per profile:

syncfm profile add proxied ... --proxy socks5h://127.0.0.1:1080

Accepted schemes are:

  • http
  • https
  • socks5
  • socks5h

A value without a scheme defaults to SOCKS5:

127.0.0.1:1080  →  socks5://127.0.0.1:1080

The URL must include a hostname and valid port if one is specified. Paths other than /, queries, and fragments are rejected. Proxy support includes socksio as a package dependency.

Error translation

Built-in adapters translate pylast failures into SyncFM exceptions:

  • transport failures become NetworkConnectionError;
  • malformed responses become InvalidNetworkResponseError;
  • authentication-related service statuses become AuthenticationError;
  • known transient service statuses become NetworkConnectionError; and
  • other pylast failures become the general NetworkError.

Only NetworkConnectionError participates in per-track retry behavior.

Custom integrations

Projects can supply their own structural MusicNetwork implementation without changing NetworkFactory. See Using syncfm-core in Python. The high-level service currently expects both source and target objects to implement the full protocol even though their actual roles use different capabilities.

syncfm-core