racuna/filepodsyc

FilePodSync (FPS) is a protocol specification and reference implementation for syncing podcast subscriptions and playback state across multiple devices, without needing a server. The problem it solves is that existing podcast sync tools like gPodder.net, Nextcloud-gPodder, and oPodSync all depend on a running server somewhere, which is fragile to maintain and requires technical expertise to self-host. FilePodSync replaces the server with a plain folder that any file-syncing service can replicate: Dropbox, Syncthing, Google Drive, Filen, iCloud, or a NAS (a personal home file server). The sync state lives entirely in a set of JSON files inside that shared folder. There is no API, no OAuth login, and no server software to run. Each device writes only to its own files and reads from all devices' files when merging. For subscriptions and episode states (like play position or "played" status), the protocol uses a strategy called Last-Write-Wins at Element Level: each record carries a timestamp, and the most recent change to any individual episode wins when two devices disagree. For the playback queue, the list of episodes you plan to listen to next, it uses an operation log instead, because "last write wins" would silently drop episodes added offline on one device. To handle offline edits safely, the sync cycle tracks three states: the last version written to disk, a merged version combining that with any changes from other devices, and a final version that layers the user's own unsaved actions on top. This ensures that a pause or subscription made while offline is not overwritten when the device reconnects. The full README is longer than what was provided.