SoulSync Documentation

The SpotifyClient provides fallback capabilities to the iTunesClient to ensure high availability of metadata. The behavior depends on the method type:

Search Methods

search_tracks, search_albums, and search_artists always try Spotify first. If any exception occurs, they fall through to iTunes.

ID-based Methods

get_track_details, get_album, get_album_tracks, get_artist, and get_artist_albums try Spotify first. They only fall through to iTunes if the provided ID is numeric (id_str.isdigit()). If the ID is alphanumeric (Spotify format) but Spotify fails, the method returns None or [] and does not attempt an iTunes lookup.

User-specific Methods

Methods like get_user_playlists and get_saved_tracks are Spotify-only and have no fallback to iTunes.

To ensure consistency across different metadata providers (Spotify vs. iTunes), SoulSync uses unified dataclasses. These objects normalize fields like id, name, artists, and album regardless of the source.

Key Fields in UnifiedTrack:

• id: A unique identifier (prefixed with itunes: if from iTunes).
• source: The MetadataSource used (e.g., SPOTIFY_OAUTH, ITUNES).
• spotify_id / itunes_id: Original source IDs for cross-referencing.
• popularity: Available for Spotify sources; defaults to 0 for iTunes.
• isrc: International Standard Recording Code (Spotify only).

Key Fields in UnifiedArtist:

• followers: Available for Spotify sources.

Key Fields in UnifiedAlbum:

• total_tracks: Number of tracks in the album.
• explicit: Boolean indicating explicit content.

All /api/v1/ endpoints (except the bootstrap endpoint) require authentication. Keys are prefixed with sk_.

Authentication Error Codes

Rate Limiting

Requests are limited to 60 per minute per IP address. Exceeding this limit returns 429 RATE_LIMITED.

SoulSync uses a tiered priority system for metadata and search operations. This allows the platform to provide immediate functionality to users without requiring them to set up Spotify Developer credentials or complete OAuth flows.

Priority Order of Access Methods:

1. Spotify OAuth: Full feature set including playlists, library, search, and metadata. Requires user credentials and OAuth flow.
2. Spotify Client Credentials: Provides search and metadata functionality but requires application client_id and client_secret.
3. Anonymous Spotify Access: Provides search and metadata functionality with no credentials required.
4. iTunes Search API: Provides search and metadata functionality with no credentials required, using a different data source.

SoulSync supports multiple user profiles. To perform actions (like adding to a watchlist) or retrieve discovery data for a specific profile, include the X-Profile-Id header in your request. If omitted, the request typically defaults to the primary profile.

Example: Adding an artist to the watchlist for profile ID 2 using Python:

requests.post(
    f"{API_URL}/watchlist",
    headers={**headers, "X-Profile-Id": "2"},
    json={"artist_id": "4tZwfgrHOc3mvqYlEYSvnL", "artist_name": "Daft Punk"}
)

The Automation Engine is a visual drag-and-drop builder for creating custom workflows using Triggers, Actions, and Signal Chains.

Triggers

Common triggers include:

• Schedule / Daily/Weekly Time
• Track Downloaded / Batch Complete
• Playlist Changed / Discovery Complete
• Watchlist Match / Wishlist Item Added
• Library Scan Complete

Actions

Common actions include:

• Process Wishlist / Scan Watchlist
• Sync Playlist / Discover Playlist
• Scan Library / Database Update
• Quality Scan / Full Cleanup
• Discord/Telegram/Pushbullet notifications

Signal Chains

Automations can communicate via signals. One automation can fire a signal (e.g., signal:foo), which another automation listens for. SoulSync includes cycle detection, chain depth limits, and cooldowns to prevent runaway loops.

SoulSync returns different data structures depending on the method called. Consumers must be prepared to handle both Dataclass instances and raw Dictionaries.

Return Type Mapping

Access Patterns

• For Dataclasses: Use attribute access: track.name, track.artists.
• For Dicts: Use key access: track_details['name'], track_details['album']['name'].