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

pub use config::Config;

pub use config::Defaults;

pub use config::EffectiveSettings;

pub use config::FlagOverrides;

pub use config::SourceConfig;

pub use reconcile::Action;

pub use reconcile::AlbumDesired;

pub use reconcile::ArtifactKind;

pub use reconcile::Desired;

pub use reconcile::DesiredArtifact;

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

ArtifactState

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

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 Suno account a library belongs to, pinned on first use.

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.

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.

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.

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.

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

render_clip_details

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

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.

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.

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.