Not a member of Pastebin yet?
Sign Up,
it unlocks many cool features!
- ---- Sound Profiles V1 Proposal (Draft 2) ----
- 0. Introduction
- Right now, our audio behavior is spread across scripts, scenes, and project
- settings. That makes it harder to change, easier to break unintentionally, and
- difficult to predict how one tweak will affect other gameplay states. It also
- forces designers to rely on programmers for even small adjustments, like trying
- a new mix, swapping a preset, or rewiring an audio asset, because those changes
- often require touching scene files or code.
- Sound Profiles solve this by introducing a clear, centralized layer of
- abstraction for audio. Instead of editing scenes or code, the team can iterate
- on audio behavior safely in one, dedicated place, reducing risk to scene
- integrity and keeping changes consistent, controlled, and easy to maintain.
- 1. Overview
- A Sound Profile is a self-contained JSON-based format describing how audio
- should behave within specific game contexts, without modifying scenes, scripts,
- or assets directly. The schema's main goal is to provide an abstraction layer
- for defining audio behavior separately from script behavior, while being
- accessible enough for non-technical team members to comfortably create and edit.
- These profiles can be layered and swapped based on any kind of game state or
- condition, all with minimal coordination necessary between the technical and
- non-technical team members, hereon referred to as "programmers" and "designers"
- respectively.
- 1.1 Pain Points Addressed / Why This System Exists
- Without Sound Profiles:
- * Audio behavior is scattered between scripts, scenes, or project settings,
- which makes modification more difficult and unpredictable.
- * Changing settings relevant to one state often risks unintentionally
- affecting others.
- * Designers would need programmers to tweak even the simplest of audio logic
- or asset wiring, as trying new mixes, presets, etc. requires touching scene
- files or code directly.
- With Sound Profiles:
- * Audio behavior is centralized to two file types (excluding whatever form
- sound categories and IDs take) that are external to any script or scene data.
- * Any designer or programmer can adjust audio behavior in isolation, making
- its definitions predictable and testable.
- * The extent to which coordination is necessary between designers and
- programmers is greatly reduced, and is mostly limited to agreeing on what
- profile(s) a given context(s) is relevant to and vice versa, as well as
- their name and use case.
- * Global accessibility mixes or effect chains become simple, if not one-line swaps.
- * Context-based mixing becomes trivial: transitions, menus, cutscenes, etc.
- * Future dynamic systems (ducking, RTPCs, property interpolation),
- get a stable backbone.
- * Schema allows for future, interactive authoring tools to be integrated.
- 2. Sound Profiles
- Modularity within a given profile is one of its main design principles.
- Each profile is effectively a container that requires a minimal amount of
- boilerplate, followed by any number of desired "property" objects. (!!! CITE;ELABORATE)
- These property objects define a wide range of settings and behaviors,
- from sound effect / sound category gain adjustments, to per-bus effect chains.
- A single Sound Profile can do any number of things. However, limiting each one
- individually to serve 1-3 purposes is ideal in order to maximize modularity and
- reusability. For example, within a single profile, you could define an audio
- effect chain that can be used in multiple *Profile Contexts* (see sect. 2.2),
- where any change to that profile's settings would apply to any associated
- contexts, like a macro of sorts.
- 2.1 Profile Definitions
- At a high level, a profile contains the following *required* fields:
- * A schema version number (integer; 1 for V1)
- * A profile ID string
- Followed by some combination of the following *optional* fields:
- * Comments, in the form of an array of strings.
- * 'overwrite' vs. 'append' boolean that determines how that profile applies
- its properties (ignored in V1; always set to overwrite). (!!! CITE;ELABORATE)
- * Any number of valid profile properties. Each property type will have its
- own dedicated mini-schema. (!!! CITE;ELABORATE)
- All fields, required or not, are agnostic relative to their order in a profile,
- and can be placed in any desired order, as long as each are placed at the
- top-level of a profile. Profiles have a flat, top-level layout relative to the
- profile's root in order to further simplify its schema.
- While V1 only supports overwrite for its load behavior, the structure should
- still accommodate 'append' (e.g., for additive/multiplicative gain or
- effect-chain extensions) load behavior to be added later with minimal
- redesigning of the schema.
- 2.2 Profile Contexts
- In order to separate audio pipeline behavior from anything implementation or
- game design-specific, profiles are instead attached to Profile *Contexts*.
- These are named identifiers that can represent *any* game state, such as:
- * Scene transitions
- * Menu screens
- * Map mode vs. NPC mode
- * Accessibility modes (e.g., "Soft Mix")
- * Any arbitrary state/tag/event the game defines later
- This abstraction allows the underlying profile format to remain stable, even
- if the game's notion of "state" evolves or expands.
- One Profile Context can theoretically contain multiple profiles to be applied
- all at once, and each profile can theoretically be attached to multiple contexts.
- In future versions, it should be possible to bind certain parameters within
- a context to more specific, real-time states, like attenuating the game's volume
- globally whenever the game window goes out of focus, for example.
- 2.3 Context Definitions
- Profile Contexts are defined in a separate JSON file that contains a context
- ID, followed by an (optional) "priority" index (see sect. 2.4), followed by
- references to profile IDs in an array. Each profile's load order is determined
- by their placement in that array.
- A context ID simply maps a name (e.g., "UI_MAINMENU", "CTX_CUTSCENE") to a
- profile (or profiles) that will be considered active while that context is live.
- 2.4 Global Contexts
- Some profiles must always be applied before or after any other context or only
- a select number of contexts, such as:
- * Accessibility mixes (e.g., Soft Mix vs. Normal Mix)
- * System-level music selection rules
- * Baseline gain adjustments
- These profiles' load order is determined by the previously mentioned "priority"
- index, which is 0 by default. Values lower than a given priority will result in
- that context being applied *before* the other, whereas values higher than a given
- priority will result in it being applied *after* the other. For example,
- a priority of -1 will be applied before a priority of 0, which will too go before
- a priority of 1, and so on. If two contexts have the same priority value, the
- load behavior is determined by the order in which the context files are read.
- With this system, implementing 'global' contexts is as simple as giving a
- context a very low or high index, while tying its state to something fairly
- static, like a value that is only set by the user adjusting an in-game setting.
- This lets the team swap global mixes dynamically (e.g., toggling Low-Intensity
- mode) without altering any other Profile Context.
- 3. Structure Guidelines
- (TBD)
- (field types are identified implicitly by its key name)
- (profile or profile context ids don't necessarily need to be all-caps)
- 3.1 Profile Structure Example
- {
- "version": 1,
- "profile_id": "SINGLE_LOWPASS",
- "append": false,
- "comments": [
- "A special 'comments' field is desired, if not necessary,",
- "due to the fact that JSON itself does not have comments as a feature.",
- "However, formatting comments in this manner may also have a use case",
- "related to any future interactive authoring tools."
- ],
- "effects_DSP": [
- <EFFECT SCHEMA TBD>
- ]
- }
- 3.2 Profile Context Structure Example
- {
- "version": 1,
- "context_id": "LPF_ENABLED",
- "priority": 2,
- "comments": [
- "For consistency (among other things),",
- "contexts should have support for comments as well."
- ],
- "profiles": [
- "SINGLE_LOWPASS"
- ]
- }
- ?. Footnotes / Implementation Notes
- (These will be assigned as actual footnotes in the final Google Doc!)
- * "RTPC" stands for "Real-Time Parameter Control"
- * Only one instance of each property type can exist per profile.
- An error is to be handled in the event of a malformed or duplicate property key.
- * The property key strings should be verbose enough to serve as the canonical
- specification name, with little to no elaboration (e.g., "effects").
- * Sound categories and IDs are TBD; schema in V1 spec should/will accommodate both.
- * Linear <-> dB conversion rules must be documented in specification.
- * Effect preset system is TBD and may be added as a 'V1.1' extension.
- Personal Notes (not to be included in the final gdoc):
- should overwrite vs. append be placed inside the profile itself,
- or in each profile context, where the profile ID is the key, and the
- overwrite/append boolean is that key's value?
Advertisement
Add Comment
Please, Sign In to add comment