Crate suno_core 

Core engine for rs-suno: library selection, sync reconciliation, and tagging.

Runtime-agnostic and free of direct IO. Network access happens through the Http port, which a CLI adapter implements, so the engine stays testable in isolation.

Re-exports

pub use config::AccountConfig;

pub use config::AreaMode;

pub use config::AreasConfig;

pub use config::AudioFormat;

pub use config::Config;

pub use config::Defaults;

pub use config::EffectiveSettings;

pub use config::FlagOverrides;

pub use config::Settings;

pub use config::SourceConfig;

pub use config::StemFormat;

pub use config::VideoCoverRetention;

pub use desired::ArtifactToggles;

pub use desired::LIKED_PLAYLIST_ID;

pub use desired::PlaylistInput;

pub use desired::build_desired;

pub use desired::build_playlist_desired;

pub use desired::clip_stems;

pub use reconcile::Action;

pub use reconcile::AlbumDesired;

pub use reconcile::ArtifactKind;

pub use reconcile::Desired;

pub use reconcile::DesiredArtifact;

pub use reconcile::DesiredStem;

pub use reconcile::LocalFile;

pub use reconcile::Plan;

pub use reconcile::PlaylistDesired;

pub use reconcile::SourceMode;

pub use reconcile::SourceStatus;

pub use reconcile::album_desired;

pub use reconcile::area_authoritative;

pub use reconcile::area_fully_enumerated;

pub use reconcile::deletion_allowed;

pub use reconcile::narrows_downloads;

pub use reconcile::plan_album_artifacts;

pub use reconcile::plan_playlist_artifacts;

pub use reconcile::reconcile;

Modules

config

Configuration model and precedence resolution.

desired

Pure desired-state construction: clip target entries and playlist manifests.

reconcile

The pure reconcile engine: it decides what to download, retag, rename, reformat, and delete.

select

Pure clip selection and filtering.

Structs

AlbumArt

The reconciled folder-art state for one album (one stable root id).

AlignedLine

One aligned line: its text, span, section label, and nested words.

AlignedLineWord

One word within a line, from the nested aligned_lyrics[].words list.

AlignedLyrics

A clip’s aligned lyrics: the flat word list and the line list.

AlignedWord

One force-aligned word from the flat aligned_words list.

AreaListing

One area’s listing outcome for the multi-area planner.

ArtifactState

The prior known state of one external sidecar artifact for a clip.

AttributionEdge

An attribution edge derived from a clip’s nested clip_roots list.

BillingInfo

The authenticated account’s billing snapshot: credits, quota, account status, plan identity, and entitlements.

CacheEntry

A cached root resolution for one clip: the O(1) album lookup, kept monotonic.

ClerkAuth

Manages the Clerk cookie and the JWT lifecycle for one account.

Clip

One finished Suno track, flattened from the API’s nested response shape.

ClipRoot

One remix/attribution origin from a clip’s nested clip_roots.clips[] list.

Cover

An embedded cover image: its raw bytes paired with its MIME type. The MIME travels with the bytes so the executor can embed an animated image/webp where the container allows it (FLAC within its size cap, MP3, WAV) or a static image/jpeg otherwise.

Edge

One parent link of a clip, for the later lineage graph store.

ExecOptions

Tunables for one execute run.

ExecOutcome

The result of applying a Plan: per-action counts and the failure list.

Failure

One action that could not be applied, for the run summary and failure log.

FfmpegError

An ffmpeg transcode failure, carrying a kind and a human-readable, secret-free reason.

FileStat

On-disk facts about one path, as probed by Filesystem::metadata.

FsError

A filesystem failure, carrying a kind and a human-readable, secret-free reason.

HistoryEntry

One entry in a clip’s history or concat_history, mirroring the API’s per-segment lineage record. Ids are stored verbatim (any m_ prefix is left for the resolver to strip).

HttpRequest

A request the engine wants an adapter to perform.

HttpResponse

The response an adapter returns to the engine.

LineageContext

The resolved lineage of a single clip, threaded into naming, tagging, and change detection.

LineageStore

The whole lineage graph, kept relational for a clean SQLite migration.

M3u8Entry

One ordered entry in an extended-M3U8 playlist.

Manifest

The full prior download state, keyed by clip id.

ManifestEntry

One manifest record: the prior known state of a single downloaded clip.

MediaUrl

One audio asset from a clip’s top-level media_urls list.

NamingConfig

NamingRequest

Node

One clip in the graph. Mirrors the fields lineage needs to survive a purge: enough to name and date the clip long after Suno deletes it.

Owner

The identity guard pins a library to the account it is first synced against and refuses to run it against a different account, so a mistyped or swapped token can never make one account’s clips look absent from source and delete another account’s files. user_id is the stable identity; display_name is cosmetic (for messages) and refreshed opportunistically on a match.

PendingCheck

One clip’s synced-lyrics outcome this run, for the caller to record as a manifest SyncedLyricsCheck once the .lrc write (if any) has safely landed.

Playlist

One of the account’s own playlists, as listed by /api/playlist/me.

PlaylistState

The reconciled .m3u8 state for one playlist.

Ports

The IO ports the executor drives, grouped so one value threads them through.

RenderedName

Resolution

The outcome of resolve_roots: a root for every input clip, plus the ancestor clips fetched to bridge gaps.

ResolveOpts

Tunables bounding how hard resolve_roots works per call.

RootInfo

The resolved root ancestor of a clip.

Stem

One separated stem of a clip, as listed by the free, read-only stems endpoint.

StoredEdge

One parent link, keyed (for upsert) by (child_id, parent_id, edge_type, role, ordinal). A flat row, not nested under its child, so it maps directly to a lineage_edges table.

SunoClient

A client for the Suno library API, owning the account’s ClerkAuth.

SyncedLyricsCheck

The record that a clip’s synced lyrics were resolved (fetched) this run.

TrackMetadata

The metadata tags written into a downloaded audio file.

TransportError

A failure to complete a request at the transport level.

WebpEncodeSettings

Encoder settings for the animated WebP cover derived from a clip’s MP4 preview.

Enums

AdoptDecision

The PHASE 2 first-use adoption decision for a not-yet-pinned library.

AreaKind

Which kind of area a listing came from, carrying playlist identity so its .m3u8 can be maintained by id and name.

CharacterSet

EdgeRole

Whether an Edge is the clip’s primary parent or a supporting one.

EdgeType

How one clip relates to its immediate parent.

Error

An error raised by the engine.

FfmpegErrorKind

Why an ffmpeg transcode failed, so the executor can treat a full scratch disk as a systemic abort rather than a skippable per-clip fault.

FsErrorKind

Why a filesystem write failed, so the executor can treat a full disk as a systemic abort rather than one more skippable per-clip fault.

Method

The HTTP method for a request. Clerk and Suno only need these two.

OwnerGate

The PHASE 1 identity verdict: whether an authenticated account may run against a library, computed with no network (see owner_gate).

ResolveStatus

The outcome of resolving a clip’s root ancestor.

RunStatus

How an execute run ended.

TokenExpiry

The lifecycle state of the pasted __client cookie relative to now.

Constants

DEFAULT_TEMPLATE

The default relative path template.

INDEX_SCHEMA_VERSION

The schema version of the library index document.

SYNCED_LRC_RECHECK_SECS

How long a clip that resolved to no lyrics (instrumental) or to an untimed plain-text fallback is trusted before its alignment is re-checked (14 days). Bounds the re-fetch to catch alignment Suno may compute after generation.

SYNCED_LRC_VERSION

The change-detection version for the synced .lrc body. Bump this when the rendered .lrc format changes so existing sidecars are rewritten on the next run (their stored hash then no longer matches, exactly as edited content would move a content_hash).

TOKEN_EXPIRY_WARN_DAYS

Warn when the pasted __client cookie is within this many days of expiry.

Traits

Clock

The time and delay port.

Ffmpeg

The ffmpeg port the executor transcodes through.

Filesystem

The disk port the executor writes the plan through.

Http

The HTTP port an adapter implements for the engine.

Functions

adopt_decision

Decide how to adopt a not-yet-pinned library from this run’s listing.

adoption_enumerated

Whether first-use adoption can confirm identity from this run’s listing.

apply_synced_lrc

Resolve each clip’s desired .lrc artifact from the fetched alignment, returning the checks to persist for the clips that were successfully fetched.

area_enumerated

Whether this area is authoritative for deletion, applying the empty-mirror guard (§5) against the final mode.

area_mode

This area’s mode after the copy-verb / force-additive override.

art_hash

A sentinel for the embedded cover art: a digest of the selected art URL, or the empty string when the clip carries no art. A mismatch against the manifest means the file on disk holds stale art even if its tags are current.

art_url_hash

A stable digest of an artifact source URL (FNV-1a), or the empty string when url is empty.

attribution_edges

Every attribution edge from a clip’s clip_roots (empty when absent).

build_modes_by_id

Fold every area’s clips into modes_by_id, mapping each clip id to the deduplicated, canonical-order list of every area mode holding it.

build_scoped_playlist_desired

Build the .m3u8 desired state for an area-scoped run (no authoritative Library). Only the playlist and liked areas that fully enumerated their members are rendered, and only when members_intact (the union was not truncated by --limit/--since, so desired still holds every member); every other stored playlist id is protected so no .m3u8 is rewritten or deleted from a partial view (B2/D3).

classify_token_expiry

Classify a cookie’s exp against now_unix and a warning window_secs.

content_hash

A stable sentinel over an arbitrary generated text artefact.

edge_type

Classify a clip’s relationship to its parent, purely from its structure.

execute

Apply plan to disk, updating manifest and albums in place, and return the outcome.

flac_picture_data_budget

The largest image-data payload that fits a FLAC PICTURE block for a cover of the given mime and an empty description. The executor uses this to decide whether an encoded animated WebP fits FLAC, and tag_flac enforces it.

immediate_parent

The clip’s primary parent id and the edge that links them.

is_downloadable

Whether a clip is a finished track worth downloading.

library_authoritative

Whether a Library area is present and fully enumerated (the implicit protector counts; library="off" leaves no Library area, so this is false).

lineage_edges

Every parent link of a clip: the primary parent plus any secondaries.

meta_hash

A sentinel for the clip’s embedded tag set.

owner_gate

Decide whether an authenticated account may run against a library (PHASE 1).

playlists_enumerated

Whether the scoped .m3u8 desired set may authorise playlist deletes: the union was not truncated (members_intact) and every playlist-rendering area (Playlist, Liked) fully enumerated. Library areas render no .m3u8, so they never gate this. Mirrors the async twin, which reports non-enumerated when a listing is partial rather than authorising a delete from a partial view (B2).

preview_synced_lrc

Adjust each clip’s desired .lrc artifact for a dry run, without any fetch.

render_clip_details

Render the plain-text per-song details sidecar for clip.

render_clip_lrc

Render an untimed .lrc sidecar for clip, or None when it has no lyrics.

render_clip_lyrics

Render the plain-text lyrics sidecar for clip, or None when it has none.

render_clip_name

render_clip_names

render_library_index

Render the whole-library index as a stable, pretty-printed JSON document.

render_m3u8

Render an extended-M3U8 playlist named name from entries, preserving their order.

render_synced_lrc

Render a synced (timed) .lrc sidecar for clip from Suno’s aligned lyrics, or None when there is nothing to time (an instrumental).

resolve_roots

Resolve the root ancestor of every clip in clips.

sanitise_name

Sanitise a free-form playlist name into a single safe path component.

source_statuses

The per-source enumeration status of every area, for the deletion verdict.

stem_file_path

The relative path of one stem file inside a song’s stems_folder.

stems_folder

The .stems sub-folder that sits beside a song’s audio file.

synced_lrc_source_hash

A stable per-clip source sentinel for the synced .lrc sidecar.

synced_lyrics_targets

The clip ids whose alignment must be fetched this run, in a stable order.

tag_alac

Tag audio (an ALAC/MP4 byte stream) with meta, returning the tagged bytes.

tag_flac

Tag audio (a FLAC byte stream) with meta, returning the tagged bytes.

tag_mp3

Tag audio (an MP3 byte stream) with meta, returning the tagged bytes.

union_clips

Build the clip union across areas in canonical order, first area winning per id so the Library payload is kept (H1).

untracked_audio

The audio paths in on_disk that no manifest entry tracks, sorted and de-duplicated.

Type Aliases

Result

A Result whose error is the engine Error.