Encodings and media URLs

Every audio master is measured and encoded moments after it lands. An encoding is one file of a recording in one codec and quality — aac-256-v1. A clip is the 30-second preview of an encoding. The original you delivered is one more file, named original.

Encoding	Made	Who may pull it
`aac-256`	for every master	`media_read`
`aac-128`, and its clip	for every master	`media_preview` or `media_read`
`flac`	for every master an organization with lossless media holds	`media_lossless`, lossless media
`mp3-128`, `mp3-320`, `mp3-v0`	on request	`media_read` (`mp3-128`: also `media_preview`)
`wav`, `alac`	on request	`media_lossless`, lossless media
`original`	—	`media_lossless`, lossless media, for lossless audio; `media_read` for artwork and video

List what exists with Resource.encodings, then mint a URL with Resource.url naming the encoding: url(encoding: "aac-256"). Ask for one made on request with requestEncoding; resource.encoded says when it is ready, so nothing needs to poll.

A family name (aac-256) follows the newest version; a pinned name (aac-256-v1) never changes, for a pipeline that must not see an encoder change. A master delivered as FLAC is its flac encoding, and a WAV master its wav encoding — both are served as the original.

Errors#

url is null with one of these in extensions.code when it cannot mint, so a missing file is never confused with a refusal:

Code	Meaning
`ENCODING_PENDING`	It is being made — usually within a minute of the file landing.
`ENCODING_NOT_REQUESTED`	Made on request: call `requestEncoding` first.
`ENCODING_NOT_AVAILABLE`	It cannot be made from this file — a lossless encoding of a lossy master, an encoding of artwork, a file that could not be analyzed.
`ENCODING_FAILED`	//SCHEMA tried and could not; we have the reason.
`LOSSLESS_NOT_ENABLED`	Your organization does not have lossless media. It comes with enterprise, and with other plans by arrangement.
`UNKNOWN_ENCODING`	No encoding by that name — see `encodingProfiles`.

A missing scope is reported as for any other field.

Operations

queryencodingProfiles
mutationrequestEncoding

The Encoding object#

One file of a resource — the original you delivered, or an encoding //SCHEMA made of it — with what was measured about it. Mint it with Resource.url.

Attributes

profileString!
What is stored — the encoding, with +clip30-v1 for a clip — or original.
encodingString!
What to pass to url(encoding:), pinned; original for the delivered bytes.
clipClipnullable
Where the clip sits in the recording. null for full length.
originalBoolean!
These are the bytes you delivered — always for original, and for flac or wav when the master already was one.
statusEncodingStatus!
READY, PENDING or FAILED.
containerStringnullable
The file format, e.g. mp4, mp3, flac, wav.
codecStringnullable
The codec, e.g. aac, mp3, flac, pcm_s24le.
losslessBooleannullable
Whether it is lossless. null for an original not yet analyzed.
bitrateKbpsIntnullable
Measured bitrate.
sampleRateHzIntnullable
Sample rate in hertz.
bitDepthIntnullable
Bits per sample, lossless files only.
channelsIntnullable
Number of channels.
durationMsIntnullable
Measured duration, in milliseconds.
byteSizeIntnullable
File size in bytes.
sha256Stringnullable
Lowercase hex SHA-256 of the file — verify what you downloaded.

The Encoding object

{
  "profile": "aac-128-v1+clip30-v1",
  "encoding": "aac-128-v1",
  "clip": { "startMs": 30000, "durationMs": 30000 },
  "original": false,
  "status": "READY",
  "container": "mp4",
  "codec": "aac",
  "lossless": false,
  "bitrateKbps": 128,
  "sampleRateHz": 44100,
  "bitDepth": null,
  "channels": 2,
  "durationMs": 30000,
  "byteSize": 482911,
  "sha256": "9b1f0c5e2a7d4c18b6e3f2a90d5c7e41b8a3f6d2c9e0b7a5f4d3c2b1a0e9f8d7"
}

The Clip object#

Where a preview clip sits in the recording.

Attributes

startMsInt!
Its start, in milliseconds from the beginning of the recording. Thirty seconds in when the recording is long enough.
durationMsInt!
Its length. Thirty seconds, or the whole recording if shorter.

The EncodingProfile object#

An encoding that can be asked for, from encodingProfiles.

Attributes

encodingString!
The pinned name, e.g. aac-256-v1.
familyString!
The family name, e.g. aac-256, which follows the newest version.
profileString!
What is stored for it — the encoding, with +clip30-v1 for its clip.
clipBoolean!
Whether this is the clip of the encoding.
codecString!
aac, mp3, flac, pcm or alac.
bitrateKbpsIntnullable
Nominal bitrate. null for variable bitrate and lossless.
losslessBoolean!
Whether it is lossless — and so needs media_lossless and an organization with lossless media.
previewBoolean!
Whether media_preview reaches it.
reachEncodingReach!
Which masters it is made for without being asked.
descriptionString!
A sentence about what it is for.

The EncodingStatus enum#

Whether an encoding can be fetched.

Values

READY
Mint it with url.
PENDING
Being made, or about to be. resource.encoded announces it.
FAILED
//SCHEMA could not make it from this master and has the reason.

The EncodingReach enum#

Which masters an encoding is made for without anyone asking.

Values

EVERY_MASTER
Every audio master, moments after it lands.
ENTERPRISE
Every audio master an organization with lossless media holds — every enterprise organization, and others by arrangement.
ON_REQUEST
Only after requestEncoding.

The MediaKind enum#

What a resource's file is.

Values

AUDIO
A sound recording. Audio a file has not yet been analyzed as anything else counts as audio.
IMAGE
Artwork.
VIDEO
A video.
OTHER
Anything else — a booklet, a text file.

List encoding profiles#

queryencodingProfiles→[EncodingProfile!]!catalog_read

The encodings your organization can use, with whether //SCHEMA makes each for every master, for the masters of organizations with lossless media, or on request. Read this rather than hardcoding names.

The list is your organization's own: organizations with lossless media — every enterprise organization, and others by arrangement — see the lossless profiles (flac, wav, alac), others see the lossy ones. It follows your plan from the moment it changes.

Arguments

None.

Returns

A list of EncodingProfile.

Request

{
  encodingProfiles {
    encoding
    family
    clip
    lossless
    preview
    reach
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "{\n  encodingProfiles {\n    encoding\n    family\n    clip\n    lossless\n    preview\n    reach\n  }\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      {
        encodingProfiles {
          encoding
          family
          clip
          lossless
          preview
          reach
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "encodingProfiles": [
      {
        "encoding": "aac-256-v1",
        "family": "aac-256",
        "clip": false,
        "lossless": false,
        "preview": false,
        "reach": "EVERY_MASTER"
      },
      {
        "encoding": "aac-128-v1",
        "family": "aac-128",
        "clip": true,
        "lossless": false,
        "preview": true,
        "reach": "EVERY_MASTER"
      }
    ]
  }
}

Request an encoding#

mutationrequestEncoding→Encoding!media_read

Ask for an encoding made only on request — an MP3 for a download store, a WAV, ALAC, or the clip of an encoding other than AAC 128. It is returned PENDING; resource.encoded announces it when ready, usually within a minute. Asking twice is one request, and asking for one that exists returns it READY.

The scope is the one minting it would need: media_lossless and an organization with lossless media for wav and alac. A lossless encoding of a lossy master is refused with ENCODING_NOT_AVAILABLE.

Encodings made on request that nobody fetches for 30 days are removed, and can be requested again.

Arguments

resourcePkInt!required
The resource.
encodingString!required
A family such as mp3-320, or a pinned encoding such as mp3-320-v1.
clipBoolean!Default: false
The 30-second clip of that encoding instead of full length.

Returns

The Encoding, PENDING or READY.

Request

mutation {
  requestEncoding(resourcePk: 771201, encoding: "mp3-320") {
    profile
    status
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  requestEncoding(resourcePk: 771201, encoding: \"mp3-320\") {\n    profile\n    status\n  }\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      mutation {
        requestEncoding(resourcePk: 771201, encoding: "mp3-320") {
          profile
          status
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "requestEncoding": {
      "profile": "mp3-320-v1",
      "status": "PENDING"
    }
  }
}