audiosalad-xml

Build, validate, and parse AudioSalad release XML from TypeScript. Targets schema v3.4. Zero runtime dependencies.

bun add @ssh/audiosalad-xml   # or npm / pnpm / yarn

This document describes 1.0, which is not published yet. npm latest is still 0.1.5, the class-only build — buildRelease, validateRelease, and parseRelease do not exist there. Everything below lands when the pending release changeset is merged.

Quickstart

import { buildRelease } from '@ssh/audiosalad-xml';

const xml = buildRelease({
    action: 'add',
    title: 'Everything I Wanted',
    displayArtist: 'Billie Eilish',
    upc: '123456789012',
    releaseDate: '2020-05-02',
    tracks: [
        {
            trackNumber: 1,
            title: 'Everything I Wanted',
            displayArtist: 'Billie Eilish',
            isrc: 'QM7G92017457',
            trackLength: 181,
            assets: [{ type: 'audio', format: 'flac', fileName: 'eiw.flac' }],
        },
    ],
});

Invalid input throws AudioSaladValidationError, carrying every problem at once:

import { AudioSaladValidationError, buildRelease } from '@ssh/audiosalad-xml';

try {
    buildRelease(input);
} catch (e) {
    if (e instanceof AudioSaladValidationError) {
        for (const { path, code, message } of e.issues) {
            console.error(`${path} [${code}]: ${message}`);
            // tracks[0].isrc [pattern]: "NOPE" does not match …
        }
    }
}

To check without throwing, use validateRelease, which returns the same issues and never throws.

Parsing

import { parseRelease } from '@ssh/audiosalad-xml';

const input = parseRelease(xml);   // -> ReleaseInput

Malformed XML throws SyntaxError. Elements outside schema v3.4 throw AudioSaladValidationError; pass { onUnknownElement: 'ignore' } to discard them.

Options

| Option | Default | Effect | |---|---|---| buildRelease(input, options):

| Option | Default | Effect | |---|---|---| | xmlDeclaration | true | Emit <?xml version="1.0" encoding="UTF-8"?> | | indent | ' ' | Indent string, or false to put the body on one line (the declaration, if emitted, still occupies its own line) | | validate | true | Set false to suppress the throw. Values that cannot be formatted at all are still omitted — this is for inspecting partial output, not bypassing the schema | | onIllegalChars | 'error' | 'strip' removes characters XML cannot represent |

parseRelease(xml, options):

| Option | Default | Effect | |---|---|---| | onUnknownElement | 'error' | 'ignore' discards elements outside schema v3.4 |

Dates

A Date is always read in UTC — the same as 0.1.x, now documented.

That is a sharp edge for calendar dates, and no formatting rule removes it: new Date(2020, 4, 2) is local midnight while new Date('2020-05-02') is UTC midnight, so any single rule reads one of them off by a day.

For calendar dates, pass a string. It is unambiguous in every timezone:

{ releaseDate: '2020-05-02' }                      // -> 2020-05-02, always
{ originalReleaseDate: '2019' }                    // partial dates are allowed
{ releaseDate: new Date('2020-05-02T00:00:00Z') }  // -> 2020-05-02 (UTC)
{ releaseDate: new Date(2020, 4, 2) }              // -> 2020-05-01 east of UTC

The last line rolls back a day in any zone ahead of UTC — Auckland, Tokyo, and the UK on summer time — and is unaffected in the Americas. Verified across seven zones.

Which fields accept what

| Field kind | Accepts | Fields | |---|---|---| | xs:date | Date, 'YYYY-MM-DD' | releaseDate | | partial_date | Date, 'YYYY', 'YYYY-MM', 'YYYY-MM-DD' | originalReleaseDate | | xs:dateTime | Date, 'YYYY-MM-DDTHH:MM:SSZ' | exportTime, globalReleaseDate, Permission.startDate/endDate, Territory.releaseDate | | xs:gYear | number | cYear, pYear |

A dateTime field rejects a bare calendar string: Territory.releaseDate needs '2020-05-02T00:00:00Z', not '2020-05-02'. cYear/pYear take a number only.

Class API

The 0.1.x classes still work, and each now has .validate():

import { Release, Track } from '@ssh/audiosalad-xml';

const release = new Release({ /* … */ tracks: [new Track({ /* … */ })] });
release.validate();   // Issue[]
release.xml();        // string
Release.sample();     // a fully populated example

Upgrading from 0.1.x

| Change | What to do | |---|---| | Delivery / Release.dspDeliveries removed | dsp_delivery was deleted from the schema in v3.4. Pin 0.1.x if you still deliver to a v3.2 endpoint. | | Permission.type is now string[] | type: 'stream' becomes type: ['stream'] | | Invalid input throws | Call validateRelease first, or pass { validate: false } | | XML declaration is emitted | Pass { xmlDeclaration: false } to restore the old output | | compilation: false is now emitted | Omit the key entirely for absence | | Multi-line text is no longer collapsed | Output is verbatim; no action needed | | parseRelease rejects non-v3.4 documents | Intended — it validates while parsing | | Node 20+ required | Upgrade your runtime |

These class field defaults are preserved: Release.action, Track.trackNumber, Permission.enabled, Territory.countryCode, PriceTier.type/name, Participant.role/primary.

0.1.x additionally defaulted every required field to an empty value (title = '', tracks = [], Label.name = '', and so on), which those constructions relied on to produce output. Those are gone: new Release({}).xml() emitted XML in 0.1.5 and now throws AudioSaladValidationError naming each missing field. That is the intended change — it is the difference between shipping empty metadata and being told what is missing.

Three element groups that 0.1.x silently dropped now appear in the output — participant/artist_id, asset/attr, and territory/permission — as does any numeric field whose value is 0 (a separate defect: falsy guards). Diff your generated XML before deploying.

What changed in schema v3.4

dsp_delivery was removed; permission/type became unbounded and gained attr; asset/md5_checksum became optional; upc_ean accepts 14 characters; and DJ Mix joined the release formats.

Contributing

The toolchain is pinned with mise:

mise install     # pinned bun + node
mise run setup   # dependencies and git hooks
mise run ci      # lint, typecheck, tests in three timezones, build, package checks

Docs

Full API reference: slingshot.github.io/audiosalad-xml

License

MIT