Variable metadataConst

Type Declaration

• cancelProbe: (operationId: string) => Promise<MetadataCancelProbeResponse>

  Stop a probe started by metadata.probeBatchAsync.

  Cancellation interrupts the in-progress disk read rather than waiting for it, and the run always finishes with a metadata:probeComplete carrying cancelled: true. Paths not yet reached are never reported, and the interrupted path is reported as neither success nor failure.

• disableDefaultLogger: () => void

  Detach the default failure logger; see disableDefaultMetadataLogger.

• embedArtwork: (
      path: string,
      opts: Omit<MetadataEmbedArtworkParams, "path" | "target"> & {
          target?: string | string[];
      },
  ) => Promise<MetadataEmbedArtworkResponse>

  Write artwork into the audio file or alongside it.

  opts.imageData is the image as raw Base64.

  opts.target selects the destination. The host takes an array; a single string is sent as a one-element array:

  • "embedded" (default) — write into the file's tag container via album_art_editor. Fails for formats the SDK cannot edit (e.g. CUE).
  • "file" — write a sibling image file in the audio's directory using fb2k's external artwork naming (cover.<ext> / back.<ext> / ...). The extension is inferred from the image's magic bytes.
  • "all" or ["embedded", "file"] — run both targets and return a results map; the call succeeds when either target succeeded.

  opts.filename overrides the auto-generated sidecar name (file mode only). It must be a plain file name: path separators are rejected, and so is a name made only of periods (., ..). Periods inside a name (cover..jpg) are fine.

  CUE / subsong paths share one sidecar per directory — this matches fb2k's per-directory external artwork lookup.

• embedArtworkBytes: (
      path: string,
      bytes: ArrayBuffer | Uint8Array<ArrayBufferLike>,
      opts?: MetadataArtworkBytesOptions,
  ) => Promise<MetadataEmbedArtworkResponse>

  Embed exact image bytes without exposing the raw Base64 wire format.

• embedArtworkFromDataUrl: (
      path: string,
      dataUrl: string,
      opts?: MetadataArtworkBytesOptions,
  ) => Promise<MetadataEmbedArtworkResponse>

  Embed a Base64 data:image/* URL; rejects malformed input.

• probeBatchAsync: (
      paths: string[],
      opts?: Omit<MetadataProbeBatchAsyncParams, "paths">,
  ) => Promise<MetadataProbeBatchAsyncResponse>

  Cancellable, non-blocking batch probe. Reads happen on a host worker thread, so unlike readBatch, a few hundred paths do not stall the UI.

  Returns a { operationId, totalCount } receipt immediately; the results arrive in batches on metadata:probeProgress and are followed by exactly one metadata:probeComplete. Each result reports where its info came from (infoSource: 'cached' | 'direct') and, on failure, which of 'not-found' / 'unsupported-format' / 'read-error' applies - the distinction readBatch collapses into one generic error string.

  Paths may carry a |subsong:N suffix and are resolved independently; they are echoed back verbatim so they work as lookup keys. Unlike metadata.read, the batch surface does not honour the legacy #N subsong spelling, which would mis-split an extensionless filename that happens to end in #<digits>.

  Path validation is all-or-nothing: if any path fails the host's media read check the whole call is rejected with PERMISSION_DENIED and no operationId is produced. Per-path rejection is not available.

• read: (
      path: string,
      opts?: Omit<MetadataReadParams, "path">,
  ) => Promise<MetadataReadResponse>

  Read structured metadata for a single track.

  Returns { success, path, tags, info }. tags preserves upstream key casing and may hold a single string or a string[] per multi-value field.

  For a track inside a container (CUE sheet, ISO image, multi-track file), either append |subsong:N to path or pass opts.cueIndex; the option wins when both are given. CUE track numbering starts at 1.

• readBatch: (paths: string[]) => Promise<MetadataReadBatchResponse>

  Batch variant; returns a results[] array with one envelope entry per requested path. Each path is resolved independently and may carry its own |subsong:N suffix; there is no batch-wide subsong option.

• readByPath: (
      path: string,
      opts?: Omit<MetadataReadByPathParams, "path">,
  ) => Promise<MetadataReadByPathResponse>

  Flat-form single-track read — every tag and technical-info field becomes a top-level field, upper-cased by the host, alongside success / path. The return shape is intentionally loose because the host forwards whatever tags the file happens to carry. canonicalPath appears only on the file-open failure envelope.

  Container tracks are addressed the same way as read().

• readRaw: (
      path: string,
      opts?: Omit<MetadataReadRawParams, "path">,
  ) => Promise<MetadataReadRawResponse>

  Read structured metadata straight from the file, bypassing the host's metadb cache; the result carries source: 'file'.

• removeEmbeddedArt: (
      path: string,
      opts?: Omit<MetadataRemoveEmbeddedArtParams, "path">,
  ) => Promise<MetadataRemoveEmbeddedArtResponse>

  Remove embedded artwork: one type, or every picture when type is omitted or removeAll is set.

• removeField: (
      path: string,
      field: string,
      opts?: Omit<MetadataRemoveFieldParams, "path" | "tags">,
  ) => Promise<MetadataRemoveFieldResponse>

  Remove a single tag field.

• removeTag: (
      path: string,
      tags: string[],
      opts?: Omit<MetadataRemoveTagParams, "path" | "tags">,
  ) => Promise<MetadataRemoveTagResponse>

  Remove one or more tag fields from a file.

• write: (
      path: string,
      tags: JsonObject,
      opts?: Omit<MetadataWriteParams, "path" | "tags">,
  ) => Promise<MetadataWriteResponse>

  Queue tag updates and signal completion via metadata:writeComplete. The returned receipt describes the dispatch; the final outcome is on the event payload.

  String arrays replace all values of a tag; an empty array removes it. Non-string, empty or NUL-containing array elements fail the entire track with INVALID_PARAMS before any of its tags are queued.

• writeBatch: (items: MetadataWriteBatchItem[]) => Promise<MetadataWriteBatchResponse>

  Queue one write per entry. When any entry fails (for example one without tags or with an invalid tag array), the call resolves as a failure envelope that still carries successCount, failCount and errors; the other entries were dispatched all the same.