SoundForge

SoundForge 0.2.2 discovers and archives reusable music and game-oriented sound effects through official provider APIs. It uses Wikimedia Commons because Commons exposes original audio URLs, exact sizes, durations, MIME types, SHA-1 checksums, categories, creator attribution, and current per-file license metadata without requiring shared credentials.

SoundForge accepts only commercial-capable license families by default: CC0, provider-designated public domain, CC BY, and CC BY-SA. Generic Commons public-domain metadata is recorded as Public-Domain; SoundForge reports PDM-1.0 only when the metadata explicitly identifies the Public Domain Mark. Unknown, noncommercial, no-derivatives, legacy sampling, mismatched license URLs, and attribution licenses without usable artist or credit evidence are rejected. Copyright status does not remove trademark, privacy, publicity, cultural, or personality-right restrictions; review each source page for your use case.

use soundforge::{ArchiveOptions, SoundForge, SoundKind, SoundTarget};

let forge = SoundForge::with_user_agent(
    "my-audio-tool/1.0 (contact@example.com)",
)?
.with_discovery_limit(20);

let sounds = forge.discover(
    &SoundTarget::Search("laser".into()),
    SoundKind::GameAudio,
)?;

let summary = forge.archive(&sounds[..1], &ArchiveOptions::default())?;
assert!(summary.is_success());
# Ok::<(), soundforge::SoundForgeError>(())

Targets include search:<query>, category:<Commons category>, file:<Commons file title>, a Commons file URL, top, and latest. Bare text is treated as a search. Music and game-audio kinds tune category searches and relevance scoring without pretending that a tag proves game provenance.

Search results use normalized whole-token and phrase matching, kind-specific signals, API ordering, and cross-wiki usage as ranking evidence. usage_count_complete states whether bounded Action API continuation completed, so a truncated count is never presented as exact. Latest results follow the API generator index from newest to oldest.

Game-audio ranking favors explicit sound-effect, UI, ambience, game, and known effect-library signals while demoting scientific, speech, news/radio, interview, podcast, and long-form material. These are ranking signals rather than provenance claims; source-page review remains required.

Downloads are HTTPS-only from upload.wikimedia.org. Unsupported MIME types are rejected before transfer; retained files must pass format magic checks, exact Commons size and SHA-1 verification, and a local BLAKE3 digest. Replacement uses staging and rollback-aware commits. With skip_existing, complete matching archives are verified and skipped, while recognized corrupt archives are repaired without relaxing symlink or ownership protections.

soundforge-audio.json retains the canonical source page, normalized license, canonical license URL where applicable, plain-text artist, credit, usage terms and description, a separately retained credit URL when available, the provider license label, raw attribution-required value, metadata retrieval time, MIME/duration/category metadata, usage-count completeness, and integrity evidence. Creative Commons HTTP URLs are upgraded only after their family, version, and path match the provider label.

SoundForge does not scrape Commons pages or mirror its catalog. It uses bounded Action API requests, a descriptive User-Agent, maxlag=5, explicit API-envelope errors, at most three attempts for rate-limit/server/maxlag failures, no more than five seconds of retry waiting, and bounded metadata continuation.

AGENT_GUIDE.md ships in the crate package and documents query, rights-preflight, attribution, ranking, archive, integrity, retry, host, and MIME behavior with public-API examples. Its exact contents are also embedded as soundforge::AGENT_GUIDE.

Development

cargo fmt
cargo test
cargo clippy --all-targets -- -D warnings
cargo doc --no-deps
cargo package