Library file format

`library.json`

An exported Audio Forge library is a ZIP archive containing a library.json descriptor and its audio files. The current machine-readable schema is:

Audio Forge library schema v1

JSON integers and decimals are both valid for fields with the number type. For example, "ambianceDuckingPercent": 0 and "ambianceDuckingPercent": 0.0 are equivalent.

The descriptor contains exactly one top-level property. Its name is the library’s display name. The library may contain Music, Ambiance, and the legacy Sound section. Each section maps category names to category objects.

{
  "My Library": {
    "Music": {
      "Battle": {
        "name": "Battle",
        "packName": "user",
        "enabled": true,
        "oneShot": false,
        "iconType": "fontIcon",
        "targetVolume": 1.0
      }
    },
    "Ambiance": {
      "Thunder": {
        "name": "Thunder",
        "packName": "user",
        "enabled": true,
        "oneShot": true,
        "ambianceDuckingPercent": 0
      }
    }
  }
}

Only name is required in a category object. Omitted optional fields use the defaults shown below. A field marked nullable may also be set to null.

Field	JSON type	Default or meaning
`name`	string	Required category display name
`packName`	string or null	Empty string
`packId`	string or null	No associated pack
`icon`	integer or null	Material folder icon code point
`iconFamily`	string or null	`MaterialIcons`
`iconPackage`	string or null	No icon package
`iconRef`	object or null	Registry reference with `pack`, `name`, and optional integer `version`
`color`	integer or null	ARGB color integer; grey when omitted
`isDefault`	boolean or null	`false`
`singleLoop`	boolean or null	`false`
`oneShot`	boolean or null	`false`; use `true` for an Echo category
`singlePlayTransitionTo`	string or null	Empty string
`singlePlayTransitionMs`	integer or null	Timer duration in milliseconds
`singlePlayTransitionTrackCount`	integer or null	`1`
`singlePlayStopPlayback`	boolean or null	`false`
`timerEnabled`	boolean or null	`false`
`enabled`	boolean or null	`true`
`index`	integer or null	`-1`
`key`	string or null	No marketplace category key
`minPause`	integer or null	Minimum pause in milliseconds; `0`
`maxPause`	integer or null	Maximum pause in milliseconds; `0`
`crossfadeDuration`	number or null	Seconds; `0`. Negative values overlap tracks
`transitionsEnabled`	boolean or null	`false`
`nameIntl`	object or null	Locale-to-name string map
`version`	integer or null	Category data version
`initialVolume`	number or null	Initial internal gain; no override when omitted
`targetVolume`	number or null	Target internal gain; no override when omitted
`initialTransition`	integer or null	Initial transition in milliseconds
`initialPlaybackSpeed`	number or null	Playback speed multiplier
`ambianceDuckingPercent`	number or null	Music ducking percentage from `0` to `100`
`iconType`	string or null	`fontIcon` or `customIcon`; defaults to `fontIcon`
`customIconPath`	string or null	Path of the custom icon inside the library

Category volume fields in library.json use Audio Forge’s internal gain range, where 1.0 is unity and 2.0 is the boosted maximum. This differs from the Local API’s normalized 0.0 to 1.0 display scale.

Archive paths

Audio files use the category names from library.json:

library.json
Music/Battle/battle-theme.ogg
Ambiance/Thunder/thunder.ogg

Custom icon files exported by Audio Forge are stored under user_icons/. Optional transition metadata is stored in transitions/transitions.json, and optional saved states are stored in saved_states.json.

Audio Forge validates the complete descriptor before modifying a library. An invalid field produces an error containing its library, section, category, and field path.