CEP 4.1 Spesification
SOPCOS Brain Lab
Canonical Protocol Specification v4.1
Overview
SOPCOS Cognitive Experience Protocol (CEP) is a platform-independent
declarative specification shared by the Audio Engine, Web, Mobile,
Visual Engine and AI.
Changelog (v4.0 → v4.1)
Added oscillate and keyframe automation modes (in addition to
constant and ramp), to support periodic and irregular
multi-point automation curves observed empirically in
reverse-engineered reference recordings.Added formal JSON Schema (automationProperty) for all four
automation modes, with additionalProperties: false and numeric
bounds.Added spatial_mode under audio.environment, defining the
low-level DSP rendering strategy for 3D spatial audio.Added ordering/clamping/fallback rules to Execution Semantics for
the new modes.Added audio.cues for declarative reusable audio overlays.
Added reusable MP3 clip playback with independent source clip
ranges, timeline trigger positions, gain, fade, loop and priority
controls.Added audio.guided.enabled as an explicit switch for the guided
overlay layer.Added guided voice prompts as a first-class cue use case.
Added shadow/masking rendering for clean voice assets, allowing
runtime low-pass filtering and pink/brown noise masking without
pre-rendering the processed voice asset.Added audio.environment.background for optional looped
ambient/music backgrounds with configurable gain, active window and
loop crossfade.Added biometric runtime input support for heart_rate and spo2.
Added biometric threshold conditions with windowed aggregation,
hysteresis and cooldown semantics.Defined biometric input as observation/trigger data only;
interpretation remains a post-session concern.
Canonical Architecture
SOPCOS CEP v4.1
├── metadata
├── experience
├── guidance
├── assets
├── biometrics
├── audio
│ ├── synthesis
│ ├── modulation
│ ├── environment
│ │ └── background
│ └── cues
├── visual
└── stages
└── stage
├── duration
├── breathing
├── audio automation
└── visual automationRoot Objects
metadata
author, created, updated, license, language, tags
experience
Fields: - intention - session_goal - recommended_posture -
arrival_state - transition_style - difficulty - recommended_duration -
breathing
recommended_posture: seated, chair, cross_legged, lotus, half_lotus,
lying, supine, standing, walking, custom
arrival_state: calm_presence, grounded, clarity, focus, compassion,
gratitude, acceptance, creative_flow, renewal, integration, deep_rest,
emptiness, expanded_awareness, sleep_ready, energized, custom
transition_style: gentle, immersive, restorative, ceremonial,
progressive, dynamic, challenging, intense, cyclic, custom
difficulty: beginner, intermediate, advanced, expert
recommended_duration: short, standard, extended, custom
breathing.pattern: none, coherent, resonant, box, triangle,
extended_exhale, physiological_sigh, 4_7_8, wim_hof, free, custom
guidance
show_countdown, show_breath_circle, show_progress, show_stage_title,
voice_intro
eyes: closed, soft, open
assets
image, thumbnail, preview_video, preview_audio
biometrics new, v4.1
Declares whether the experience may consume runtime biometric inputs.
Fields: - enabled - required - metrics
Canonical metrics in v4.1: - heart_rate - spo2
Biometric measurements are runtime inputs and MUST NOT be embedded as
static values in the CEP document. The CEP declares conditions; the
runtime provides timestamped measurements.
audio
synthesis: - carrier_hz - waveform
modulation: - type - shape
environment: - noise_color - drone_ratio - drone_hz - drift_speed -
spatial_hz - drone_harmonics - spatial_mode new, v4
environment.background new, v4.1: - enabled - asset_url - format -
clip - active_window - gain_db - loop - fade_in_ms - fade_out_ms - bus
audio.guided new, v4.1: - enabled
audio.cues new, v4.1: - id - type - asset_url - format - clip -
trigger - bus - gain_db - fade_in_ms - fade_out_ms - loop - priority -
duck - optional shadow rendering parameters
Noise: white, pink, brown Waveform: sine, triangle, square Modulation:
am, fm, none
Spatial safety: Recommended 0.02-0.40 Hz Maximum 0.50 Hz
spatial_mode new, v4
Defines the low-level rendering strategy and DSP algorithms used to
generate 3D spatial audio and head-externalization (out-of-head)
effects. This property governs how spatial_hz and related
environment fields are realized in the signal chain - it does not change
the automated values themselves.
Enum:
auto (Default): Activates the Hybrid Panning Model. Pure
binaural carrier sine waves completely bypass the 3D delay buffers
and head-shadowing filters, to prevent phase cancellations and
protect the precise entrainment difference frequency (f_diff).
Wideband signals (multi-band noise, sub-octave drone choruses,
breathing cues) are dynamically spatialized using Interaural Time
Difference (ITD), Interaural Level Difference (ILD), and first-order
Parametric Head-Shadowing (IIR low-pass filtering) to achieve
high-fidelity externalized 3D space.stereo: Forces standard, equal-power stereophonic panning
across all channels. Completely disables the 3D spatial delay
buffers, fractional delay lines, and head-shadowing filters. Ideal
for legacy testing, flat stereo configurations, or specific artistic
requirements.hrtf_3d: Forces full 3D spatial/HRTF processing (either
convolutive or parametric) across the entire signal chain (including
pure carrier sines) where supported by the client hardware and
platform-specific renderer.
Safety note: hrtf_3d intentionally bypasses the f_diff protection
that auto provides. Client renderers that select hrtf_3d are
responsible for their own phase-cancellation safeguards on the carrier
sines; the protocol makes no entrainment-fidelity guarantee in this
mode. auto remains the recommended default for
therapeutic/entrainment-focused experiences.
visual
scene, palette, brightness, particle_density, breathing_ring, mandala,
motion_speed
Scenes: none, nebula, forest, ocean, mountains, space, stars, void,
sunrise, sunset, cave, rain, snow, clouds, fire, aurora, temple,
abstract, geometry, fractal, custom
Palettes: deep_blue, blue, cyan, teal, green, emerald, purple, violet,
gold, amber, orange, red, white, gray, monochrome, rainbow, earth,
sunset, aurora, custom
Mandalas: none, lotus, seed_of_life, flower_of_life, sri_yantra,
merkaba, enso, spiral, hexagon, circle, tree_of_life, custom
Stage Model
Each stage is an atomic execution block containing: - duration -
breathing override - audio automations - visual automations
Audio automations: binaural_hz, mod_depth, filter_cutoff, spatial_hz
Visual automations: brightness, particle_density, motion_speed
Automation Model
mode: - constant - ramp - oscillate new, v4 - keyframe [new,
v4]
curve: - linear - exponential - logarithmic
JSON Schema
"definitions": {
"automationProperty": {
"type": "object",
"required": ["mode"],
"oneOf": [
{
"properties": {
"mode": { "type": "string", "enum": ["constant"] },
"value": { "type": "number" }
},
"required": ["value"],
"additionalProperties": false
},
{
"properties": {
"mode": { "type": "string", "enum": ["ramp"] },
"from": { "type": "number" },
"to": { "type": "number" },
"curve": { "type": "string", "enum": ["linear", "exponential", "logarithmic"], "default": "linear" }
},
"required": ["from", "to"],
"additionalProperties": false
},
{
"properties": {
"mode": { "type": "string", "enum": ["oscillate"] },
"center": { "type": "number" },
"amplitude": { "type": "number", "minimum": 0 },
"osc_hz": { "type": "number", "exclusiveMinimum": 0 },
"waveform": { "type": "string", "enum": ["sine", "triangle"], "default": "sine" },
"phase": { "type": "number", "default": 0.0 }
},
"required": ["center", "amplitude", "osc_hz"],
"additionalProperties": false
},
{
"properties": {
"mode": { "type": "string", "enum": ["keyframe"] },
"points": {
"type": "array",
"minItems": 2,
"items": {
"type": "object",
"required": ["t", "value"],
"properties": {
"t": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
"value": { "type": "number" },
"curve": { "type": "string", "enum": ["linear", "exponential", "logarithmic"], "default": "linear" }
},
"additionalProperties": false
}
}
},
"required": ["points"],
"additionalProperties": false
}
]
}
}Audio Overlay & Cue System v4.1
CEP v4.1 introduces a declarative overlay layer that operates in
parallel with the base synthesis chain. Overlay playback MUST NOT modify
the underlying synthesis parameters, stage timing, oscillator state,
modulation state, or automation state.
The overlay layer has three primary use cases:
Guided --- audible voice guidance placed at precise points in
the experience timeline.Shadow / Masking --- a voice or suggestion asset rendered as a
spectrally attenuated and acoustically masked background texture.Background --- an optional ambient/music layer that can loop
behind the main binaural experience.
Overlay isolation principle
The canonical signal architecture is:
Base Synthesis
├── binaural carrier
├── modulation
├── noise
├── drone
└── spatial processing
│
├───────────────┐
│ │
▼ ▼
Base Bus Overlay Layer
│
┌───────┼────────┐
│ │ │
guided shadow background
│ │ │
└───────┼────────┘
▼
Mixer
│
OutputOverlay processing is a mixer/renderer concern. A cue or background
layer MUST NOT silently rewrite the base CEP synthesis or stage
automation.
Guided Audio v4.1
Guided mode provides optional voice direction using reusable external
audio assets. It is enabled explicitly:
"audio": {
"guided": {
"enabled": true
}
}When guided.enabled is false, guided cues MUST NOT be scheduled or
required for successful session initialization. Engines SHOULD avoid
loading guided assets when the layer is disabled.
A guided asset may be a longer recorded MP3 from which multiple short
segments are reused at different points in the experience.
Example:
{
"id": "guided_001",
"type": "voice_prompt",
"asset_url": "https://sopcos.io/audio/cues/som...",
"format": "mp3",
"clip": {
"start_sec": 1,
"end_sec": 5
},
"trigger": {
"mode": "absolute_time",
"t_sec": 2
},
"bus": "voice",
"gain_db": 0,
"fade_in_ms": 100,
"fade_out_ms": 300,
"loop": false,
"priority": 5,
"duck": {
"target_bus": "binaural",
"reduction_db": -8,
"attack_ms": 150,
"release_ms": 700
}
}The semantics are:
trigger identifies where the cue starts on the experience
timeline.clip.start_sec and clip.end_sec identify the segment of the
external asset that is played.Cue duration is derived as clip.end_sec - clip.start_sec.
The same source asset MAY be referenced by multiple cues with
different clip ranges.duration_sec is not required for v4.1 cue playback when clip is
present.loop applies to the selected clip, not implicitly to the whole
asset.fade_in_ms and fade_out_ms MUST be constrained to the effective
clip duration; engines MUST clamp invalid values rather than fail
the session.
Cue trigger modes
Canonical v4.1 trigger modes are:
absolute_time
stage_relative
biometric
absolute_time:
"trigger": {
"mode": "absolute_time",
"t_sec": 430
}stage_relative:
"trigger": {
"mode": "stage_relative",
"stage_index": 1,
"offset_sec": 5
}biometric is defined in the Biometric Runtime section below.
Cue buses
Canonical bus names in v4.1 are:
binaural
voice
ambient
shadow
A renderer MAY support additional implementation-specific buses. Unknown
bus names MUST NOT cause a protocol failure.
Priority
priority is used for cue scheduling/conflict resolution. It MUST NOT
be interpreted as loudness or gain. Gain remains controlled by
gain_db.
Ducking
Ducking is explicitly declarative. It is never implicit merely because a
cue is a voice_prompt.
Example:
"duck": {
"target_bus": "binaural",
"reduction_db": -8,
"attack_ms": 200,
"release_ms": 800
}Ducking operates at the mix level. It MUST NOT modify carrier frequency,
beat frequency, modulation depth, filter automation, stage timing, or
other base synthesis parameters.
Shadow / Acoustic Masking v4.1
Shadow mode is intended for cases where a clean recorded
suggestion/voice asset is placed beneath the main experience and
deliberately reduced in speech intelligibility through spectral
attenuation and acoustic masking.
The canonical asset SHOULD be a clean, lossless voice master in WAV or
FLAC format. The renderer performs the masking at runtime.
The protocol does NOT require the author to create a separate pre-masked
MP3 for every desired masking configuration.
Example:
{
"id": "shadow_001",
"type": "voice_prompt",
"asset_url": "https://sopcos.io/audio/cues/sug...",
"format": "flac",
"clip": {
"start_sec": 12,
"end_sec": 31
},
"trigger": {
"mode": "absolute_time",
"t_sec": 180
},
"bus": "shadow",
"gain_db": -18,
"fade_in_ms": 100,
"fade_out_ms": 300,
"loop": false,
"priority": 5,
"shadow": {
"enabled": true,
"filter": {
"type": "lowpass",
"cutoff_hz": 1200,
"slope_db_oct": 24
},
"noise": {
"enabled": true,
"color": "pink",
"gain_db": -14
}
}
}Canonical shadow processing:
Clean Voice
│
▼
Low-pass / spectral attenuation
│
▼
Attenuated Voice ─────┐
├──> Shadow Bus ──> Mixer
Pink/Brown Noise ─────┘Canonical noise colors are pink and brown.
The purpose of this layer is technical signal rendering: reducing speech
intelligibility through level masking and spectral attenuation. CEP MUST
NOT claim that a particular psychological, hypnotic, subconscious, or
therapeutic effect is guaranteed by the renderer.
Runtime DSP principle
Shadow processing SHOULD be performed by the audio engine at runtime so
that one clean source asset can support multiple protocols and masking
profiles. Preprocessed assets MAY be used for performance,
compatibility, or offline rendering, but they are not the canonical
authoring requirement.
Background Ambient Loop v4.1
The background layer provides an optional continuous ambient/music
texture behind the main binaural experience. It is distinct from
event-based cues.
Example:
"environment": {
"background": {
"enabled": true,
"asset_url": "https://sopcos.io/audio/ambient/...",
"format": "mp3",
"clip": {
"start_sec": 0,
"end_sec": 60
},
"active_window": {
"start_sec": 0,
"end_sec": null
},
"gain_db": -18,
"loop": {
"enabled": true,
"crossfade_ms": 2000
},
"fade_in_ms": 3000,
"fade_out_ms": 5000,
"bus": "ambient"
}
}Semantics:
clip selects the source segment that is looped.
active_window defines where on the experience timeline the
background layer is active. A null end_sec means until the end
of the session.gain_db controls the background layer's mix level.
loop.enabled controls repetition of the selected clip.
crossfade_ms SHOULD be used to avoid audible discontinuities at
loop boundaries.fade_in_ms and fade_out_ms control activation/deactivation of
the background layer.Background music is an authored playback asset and MAY be delivered
as MP3. Unlike shadow voice assets, it does not need to be lossless.
Background audio MUST remain an independent layer and MUST NOT alter the
base binaural synthesis parameters.
Biometric Runtime Layer v4.1
CEP v4.1 introduces a minimal biometric observation layer. It is
intentionally small because the current runtime source is a wearable
device that provides heart rate and SpO₂, while higher-level
physiological interpretation is performed after the session.
"biometrics": {
"enabled": true,
"required": false,
"metrics": [
"heart_rate",
"spo2"
]
}Canonical metrics in v4.1 are only:
heart_rate
spo2
HRV is intentionally not a canonical v4.1 metric. It MAY be captured by
a client outside the CEP canonical metric set, but it is not required
for v4.1 runtime semantics.
Observation, event, interpretation
CEP v4.1 separates three concepts:
Measurement --- timestamped value received from the wearable.
Event --- a runtime condition produced by
threshold/window/hysteresis evaluation.Interpretation --- higher-level analysis performed after the
session.
The CEP declares rules. It does not contain live biometric measurements.
Wearable
│
├── heart_rate
└── spo2
│
▼
Session Runtime
│
├── raw timestamped measurements
│
└── biometric condition evaluation
│
▼
cue event
│
▼
cue renderer
After session:
raw measurements + events
│
▼
post-session interpretationThis architecture intentionally avoids treating a runtime threshold
event as a clinical or psychological interpretation.
Biometric cue trigger
Example:
"trigger": {
"mode": "biometric",
"metric": "heart_rate",
"window": {
"duration_sec": 15,
"aggregation": "mean",
"max_age_sec": 5
},
"condition": {
"operator": "above",
"threshold": 95,
"hysteresis": 3
},
"cooldown_sec": 120
}Window aggregation
The window object stabilizes runtime evaluation.
Canonical v4.1 aggregation:
mean
max_age_sec is the maximum acceptable age of a measurement
contributing to the evaluation. Stale data MUST NOT be treated as
current data.
Hysteresis
Hysteresis prevents repeated trigger/release events when a biometric
metric oscillates around a threshold.
For:
"condition": {
"operator": "above",
"threshold": 95,
"hysteresis": 3
}the condition enters the active state at values above 95 and releases
only after the metric falls below 92.
Equivalent behavior:
ENTER
│
HR > 95 ───────┤────────────
│
│ active
│
HR < 92 ───────┤────────────
│
RELEASEHysteresis is a runtime stabilization mechanism. It is not an
interpretation of the user's physiological state.
Cooldown
cooldown_sec prevents repeated activation of the same cue within a
defined period after a trigger.
Cooldown MUST be evaluated per cue instance.
Missing or unavailable biometric data
If biometrics.enabled is false, biometric triggers MUST be ignored.
If biometric data is unavailable and required is false, the session
MUST continue normally and biometric cues MUST be skipped.
If data becomes stale beyond max_age_sec, the affected condition MUST
evaluate as unavailable/false until fresh data arrives.
CEP v4.1 does not require a biometric sensor for a protocol to execute
unless the author explicitly sets required to true.
Scope boundary
CEP v4.1 biometric semantics are limited to:
Observe → Evaluate condition → Trigger cueThey do not include:
Interpret → Predict → Mutate DSPReal-time ML interpretation, adaptive state estimation, and direct
mutation of binaural frequency, modulation depth, filter cutoff, or
other synthesis parameters are explicitly outside the v4.1 canonical
specification. Such capabilities may be introduced by a future
adaptive/neuroadaptive runtime extension.
v4.1 Cue JSON Shape
The canonical cue shape is:
{
"id": "string",
"type": "voice_prompt | ambient_overlay",
"asset_url": "string",
"format": "mp3 | wav | flac",
"clip": {
"start_sec": 0,
"end_sec": 10
},
"trigger": {
"mode": "absolute_time | stage_relative | biometric"
},
"bus": "voice | ambient | shadow | binaural",
"gain_db": 0,
"fade_in_ms": 0,
"fade_out_ms": 0,
"loop": false,
"priority": 0,
"duck": null
}shadow rendering parameters are optional and only meaningful when the
cue uses shadow rendering.
The authoring tool SHOULD validate:
clip.start_sec >= 0
clip.end_sec > clip.start_sec
fade durations do not exceed effective playback duration
biometric metrics are limited to canonical v4.1 metrics
cooldown_sec >= 0
hysteresis >= 0
max_age_sec > 0 when present
background loop crossfade does not exceed the effective loop clip
duration
v4.1 Rendering and Compatibility Rules
The following rules apply to all new v4.1 features:
Unknown properties MUST be ignored.
Unknown cue types MUST NOT crash or invalidate the session.
Unsupported cue trigger modes MUST be safely ignored by the
renderer.An unsupported optional overlay MUST NOT invalidate the base
synthesis session.If a background asset cannot be loaded, the base binaural experience
MUST continue.If a guided or shadow asset cannot be loaded, the base binaural
experience MUST continue.Overlay gain and ducking are mix-level operations.
Overlay processing MUST NOT mutate the base synthesis state.
Runtime biometric absence MUST NOT fail a session when
biometrics.required is false.Implementations MAY log unsupported optional features for
diagnostics.Renderers SHOULD prefer graceful degradation over session failure.
These rules extend the existing v4 forward-compatibility principle:
newer protocol features should degrade in capability, not break
correctness.
Execution Semantics
For a stage duration D and elapsed time t:
p = t / D
Constant: P(t)=V
Linear: P(t)=Vfrom+p*(Vto-Vfrom)
Exponential: P(t)=Vfrom*(Vto/Vfrom)\^p
Valid when Vfrom>0.001 and Vto>0.001.
Logarithmic: Implementation-defined logarithmic interpolation. All
engines must produce equivalent perceptual behavior.
Oscillate new, v4:
P(t) = center + amplitude waveform(2π osc_hz * t + phase)
Where waveform(x) = sin(x) for sine, and the normalized triangle
wave equivalent for triangle. osc_hz is independent of and not
constrained by the stage duration D --- a stage may contain a
non-integer number of oscillation cycles; engines must not reset phase
at stage boundaries unless the stage explicitly restarts the automation
(phase is absolute to stage-start, not free-running across stages).
Keyframe new, v4:
points MUST be sorted by ascending t by the authoring tool. Engines
encountering an unsorted points array MUST sort it before evaluation
and SHOULD log a warning; behavior on duplicate t values is
implementation-defined but MUST NOT crash the DSP chain.
For elapsed fraction p = t/D, find the bracketing points [p_i, p_i+1]
such that p_i.t <= p <= p_i+1.t, then apply the Ramp interpolation
formula above between them using p_i+1.curve.
If the first point's t is not 0.0, the value for p < points[0].t
is clamped to points[0].value. If the last point's t is not 1.0,
the value for p > points[-1].t is clamped to points[-1].value.
Authoring tools SHOULD emit points at t=0.0 and t=1.0 explicitly to
avoid relying on clamp behavior.
Value clamping (all modes): The resulting P(t) MUST be clamped to
the physically/perceptually valid domain of the target parameter before
being applied (e.g. binaural_hz clamped to >= 0; spatial_hz clamped
per the Spatial safety bounds below). This applies in particular to
oscillate, where center - amplitude may fall outside the valid
domain.
Unknown mode fallback (forward compatibility): If an engine does not
recognize a given mode value, it MUST NOT halt or error. It MUST fall
back to a degraded-but-safe static behavior: - Unknown mode with a
center field present → treat as constant using center as
value. - Unknown mode with a points array present → treat as
constant using points[0].value. - Otherwise → treat as constant
using 0 or the parameter's documented default.
This guarantees that experiences authored against a newer protocol
version degrade gracefully (losing dynamism, not correctness) on older
engines, consistent with the Safety principle that unknown properties
must be ignored.
Safety
Experience never affects DSP.
Overlay/cue playback never mutates base synthesis parameters.
Guided overlays never implicitly alter the base DSP.
Shadow masking is a signal-rendering technique; no psychological or
therapeutic outcome is guaranteed.Background loops remain independent of the base binaural synthesis.
Biometric measurements are runtime observations, not clinical
diagnoses.Biometric conditions use hysteresis/cooldown to reduce threshold
chatter.Stale biometric data MUST NOT be treated as current.
Missing optional biometric data MUST NOT fail the session.
Experience never affects DSP.
Guidance never affects DSP.
Unknown properties must be ignored.
Unknown automation mode values must degrade to a safe constant
fallback, never a DSP error (see Execution Semantics).spatial_hz must never exceed 0.50 Hz.
For oscillate automations, osc_hz must be validated against the
same spatial safety bounds as spatial_hz when applied to that
property.hrtf_3d spatial_mode bypasses f_diff protection; engines selecting
this mode are responsible for their own phase-cancellation
safeguards on entrainment carrier tones.
Versioning
Protocol Version: v4.1
This document is the canonical reference for every SOPCOS Brain Lab
implementation supporting CEP v4.1.
CEP v4.1 is backward-compatible at the conceptual architecture level
with CEP v4.0. Engines that do not implement the v4.1 overlay or
biometric features MUST continue to execute the base v4 synthesis/stage
model and MUST ignore unsupported optional properties without failing
the session.
Replies