libgms capabilities and integration manual

The platform root, frontend and desktop resolve their file dependency to gomeow.media/libgms. Do not point a product build at another product’s directory or directly at a sibling that will not exist in a container. Shared and shared-ui inside the platform are ordinary internal sharing layers, not additional canonical language repositories.

Canonical libgms and the platform vendored marker are at 8600711 for this documentation baseline; the standalone CLI is at 7798c95. The package version is currently 0.0.0, so retain the source commit/build identity when comparing behavior. A version string alone does not establish snapshot equivalence.

The actual shared DAW engine lives in the platform shared/audio layer. Plugin hosting, recording, licensing, cloud storage, authentication, queues and native device management are not supplied by importing libgms. Comments mentioning historical future phases are not evidence of implemented exports.

import { parse, getProject, getBeats } from '@gomeow/libgms/musicscript'
const source = 'project "Example" { bpm: 100 }'
const result = parse(source)
if (result.errors.length) throw new Error(result.errors[0].message)
const project = getProject(result.program)
const beats = getBeats(result.program)

ParseResult includes the program, errors and source-related data. Editor-tolerant parsing can return a partial AST: reject errors before rendering or exporting. Typed getProject/getBeats/getMelodies/getSections and related accessors help consumers avoid writing a second AST interpreter.

Bound input size at the host boundary even though individual constructs have internal limits. Treat user paths and media resolution separately from syntax. Parsing source does not authorize filesystem reads, paid generation or playback.

import { check, compileToIr } from '@gomeow/libgms/musicscript'
const source = 'beat drums { kick: [X . . .] } section loop { bars: 1 play: [drums] } structure [loop]'
const result = check(source, { engine: 'native', target: 'export' })
if (result.diagnostics.some(item => item.severity === 'error')) {
  throw new Error('Resolve diagnostics before rendering')
}
const compiled = compileToIr(source, { engine: 'native', target: 'export' })
if (!compiled.ir) throw new Error('No valid audio IR')
const payload = JSON.stringify(compiled.ir)

check combines parse diagnostics, capability analysis and semantic validation. Engines are native/web; targets are play/export/events/midi. Inspect error severity rather than assuming any returned object is usable. For assets, supply truthful host existence/readiness callbacks; do not default unavailable files or generated vocals to present.

getEngineCapabilities describes the current supported/partial/unsupported/not-applicable inventory. analyzeCapabilities and analyzeSemantics support hosts that already have an AST. They are not remote probes of a plugin or a native installation.

compileToIr performs checks and exposes ir only on success. The gms-ir schema/version and languageVersion are explicit; native hosts should reject unsupported versions and malformed values before preparing output. createIr wraps an already-validated program and is not a replacement for checking user input.

IR preserves normalized declarations and source-map spans while excluding video declarations from audio IR v1. Direct native IR consumption needs a controlled asset root and the matching native renderer. libgms does not launch that renderer or negotiate its installed version for you.

Events and MIDI are target-specific musical representations. They cannot embed sample/vocal audio or express every audio-only effect. Retain source, IR identity and render metadata when reproducibility matters.

Use canonical metadata for keywords, properties and reference entries. The source index and formatter preserve authored text where required; do not regenerate whole files from AST merely to rename or transform a note list unless that is the intended operation.

Preview helpers return data. A beat-grid or piano-roll preview is not decoded/rendered audio. Keep the current document revision with asynchronous host results so stale checks cannot overwrite diagnostics for newer text.

extractMusicScriptEvents and timing helpers share the canonical arrangement/time-map interpretation. Count expanded drum slots, use sixteenths for melody lengths, and quarter notes for video positions. Relative tempo changes and repeated sections are applied in order.

DRUM_VOICES, DRUM_ALIASES, SYNTH_VOICES and DEFAULT_SYNTH describe the browser voice catalog as pure data. The host chooses how to instantiate it. A preset name is not an exact hardware-emulation guarantee, and a native voice with the same name can sound different.

Do not infer native/web parity by comparing catalog keys. Use capabilities for the requested path and then render/listen on the actual runtime.

Import GmsExecutor (also exported as BrowserGmsExecutor) from the executor subpath only in a compatible browser/bundled host. Construct it, load a checked Program, play after a user gesture, stop as needed and dispose all owned resources when the view/session ends.

import { BrowserGmsExecutor } from '@gomeow/libgms/executor'
const executor = new BrowserGmsExecutor({
  bridge: {
    toPlayerUrl: async file => resolveApprovedLocalAsset(file),
    fetchVocalAudio: async () => { throw new Error('Prepare vocal assets explicitly') },
  },
})
await executor.load(checkedProgram)
await executor.play()
// On stop/unmount:
executor.dispose()

This fragment intentionally leaves resolveApprovedLocalAsset and checkedProgram to the host. Validate approved paths and produce host-appropriate URLs; clean up created URLs after playback. Bind results to the current session/generation and dispose late completions.

Both bridge methods have defaults when omitted. The legacy browser vocal default can read stored credentials and make a remote request. A production host should explicitly override both methods, authorize generation separately and avoid treating an omitted method as a no-network policy.

The executor does not expose a universal AbortSignal load/play contract. Cancellation in a wrapper can stop waiting before underlying work settles; arrange late cleanup. Keep licensing, paid debits/refunds, source permissions and device ownership outside the language library.

import { serializeAssetMetadata, parseAssetMetadata } from '@gomeow/libgms/assets'
const text = serializeAssetMetadata([
  { assetKey: 'kick.wav', metadata: { name: 'Dry kick', tags: ['drums'], favorite: true } },
])
const restored = parseAssetMetadata(text)

The gomeow.asset-metadata v1 document holds exact asset keys with name, tags and favorite. It is metadata, not a file transfer. Validation rejects unknown fields, duplicate/path-shaped keys, invalid strings and tag collisions. Limits include 8 MiB per document, 10,000 entries, 160-byte names and sixteen bounded tags per entry.

Hosts implement conflict review, keep/replace policy, file existence and atomic persistence. Matching a filename does not prove that bytes are identical; use the appropriate content hash for that purpose.

AssetProvenance records version, sourceAssetId, sourceSha256, provider label, credit, rightsStatement and declared rights, with optional source/package/catalog fields. AssetProvenanceEntry groups one or more records under an assetKey. parseAssetProvenance and serializeAssetProvenance validate the versioned document; validateAssetProvenance validates one record.

Accepted rights codes are PUBLIC_DOMAIN_US, PUBLIC_DOMAIN_DEDICATION, PERMISSION_GRANTED, ATTRIBUTION_REQUIRED, CC_BY_SA and UNKNOWN. Boolean fields describe redistribution, attribution and factory eligibility. A boolean is a declaration, not a license verifier.

The source SHA-256 is lowercase hexadecimal for the referenced bytes; the host must hash/check actual content. URLs are bounded HTTP(S) references without embedded credentials, not an instruction to fetch them. Preserve all relevant attribution through transformations and explain missing or uncertain rights rather than replacing them with an invented permissive code.

Documents are bounded to 8 MiB and 10,000 entries, with 1–32 records per entry and bounded text fields. Exact signatures are in the assets declaration files. No cryptographic signature or third-party permission verification is added by serialization.

buildAudioGenerationRequest validates supported music, loop, one-shot, ambience, vocal and game-transition request shapes. Game transitions require source/destination labels. buildGeneratedAssetProvenance records the declared generation inputs, model-family classification, time, duration, charged credits and license class.

These functions are pure builders. They do not contact a provider, reserve credits, grant commercial rights, retry jobs or store audio. The host must enforce authorization, costs, permitted inputs, output validation and durable debit/refund semantics.

The generation subpath still exposes a historical placeholder constant alongside implemented builders. Its presence does not mean an end-to-end voice service or a ready-made server SDK exists.

parseCompositionModule validates .gmsmodule.json v1. instantiateCompositionModule accepts bounded numeric overrides and returns source plus resolved parameters. Source outside transformed note lists is retained; the expanded result is reparsed and checked for the intended transformation.

Transforms target melody/theme notes: transpose, stretch, velocity scale, reverse and rotate. They are ordered operations with explicit bounds, not expression evaluation. Inputs with unsupported media, nested imports, beat/chord transforms or invalid result pitches/lengths fail.

A host still needs to obtain the template through an approved file picker/API, confirm draft replacement and decide where to save output. Do not make a template import implicitly execute or render.

compileVideo(program, name?) produces a gms-video plan. Choose a name when multiple video declarations exist. videoFrameClock and supported frame-rate data maintain rational timing through final frame rounding.

The compiler never opens files or validates a real codec. The consuming CLI/Desktop path must check containment, regular readable files, duration and trim bounds before decoding. Picture source audio is separate; the host supplies the soundtrack policy.

Video v1 is bounded contiguous clips, supported fades/crossfades and captions. It is not a general visual compositor. Keep its plan separate from audio IR and retain the selected source identity for export.

buildGameExportPlan prepares layers/regions, render jobs and adaptive scheduling metadata. applyGameExportProfile/getGameExportProfile select safe target naming/layout. normalizeGameWav provides the expected bounded waveform normalization path. finalizeGameExportManifest consumes rendered asset information and produces the manifest; gameMiddlewareFiles derives vendor import artifacts.

The host owns rendering, hashing real bytes, staging files, preserving an existing destination, validating path containment and checking rights. A generated manifest is not evidence that every listed audio file exists or loops cleanly.

FMOD/Wwise helpers do not connect to a vendor project or build banks. Keep scheduling metadata for application integration and verify imported assets, events and loop behavior in the target tool.

1. Use the pure subpath for parsing/checking in Node; import executor only in its compatible runtime.
2. Keep dependency resolution reproducible in clean clones, containers and release staging.
3. Make canonical language changes in libgms, build/test there, then commit and push canonical.
4. Re-sync the platform snapshot using AGENTS.md/VENDORED.md, excluding canonical .gitignore and agent instructions so committed dist remains correct.
5. Update the synced SHA, regenerate documentation and run consumer tests/typechecks.
6. Run CLI conformance and representative render checks when the contract affects native output; collect listening/vendor acceptance separately.

Never edit the platform’s vendored libgms directly. A shared code fix belongs in its canonical owner; a web/desktop UI workflow belongs in the platform. The API declaration files distributed with the package are the exact type/signature reference for that build.

• MusicScript language reference
• Web manual
• Desktop manual

Names below are read from the installed public entry point. Type-only interfaces are described by the package declarations; this inventory is not a substitute for their signatures.

Names below are read from the installed public entry point. Type-only interfaces are described by the package declarations; this inventory is not a substitute for their signatures.

Names below are read from the installed public entry point. Type-only interfaces are described by the package declarations; this inventory is not a substitute for their signatures.

Names below are read from the installed public entry point. Type-only interfaces are described by the package declarations; this inventory is not a substitute for their signatures.