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::SourceConfig;

pub use config::StemFormat;

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::deletion_allowed;

pub use reconcile::plan_album_artifacts;

pub use reconcile::plan_playlist_artifacts;

pub use reconcile::reconcile;

Modules

config

Configuration model and precedence resolution.

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.

ArtifactState

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

BillingInfo

The authenticated account’s current remaining credit balance.

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.

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.

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.

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.

OwnerCheck

The verdict of comparing an authenticated account against a library’s owner.

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 is trusted before its alignment is re-checked (14 days). Bounds the re-fetch of instrumentals to catch alignment Suno may compute shortly after a clip is generated.

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 delay port the executor waits through.

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.

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.

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.

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.

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.

lineage_edges

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

meta_hash

A sentinel for the clip’s tag-bearing metadata and chosen art.

owner_gate

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

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.

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_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.

Type Aliases

Result

A Result whose error is the engine Error.