Files

T

3dtours d5143b440a fix: change md files to md folder

2026-07-21 18:22:39 +07:00

16 KiB

Raw Blame History

Technical Directive Manual & Architectural Standards: SonicForge Studio

This document serves as the supreme and mandatory technical standard for all AI Code Agents engaged in the development, maintenance, or refactoring of the SonicForge Studio codebase. The directives below are established to completely eliminate arbitrary inferences (hallucinations), ensuring the mathematical integrity of Digital Signal Processing (DSP) and professional-grade DAW graphical layouts.

1. Critical Directives for AI Agents

No Arbitrary Rewrites: Absolutely do not alter the foundational architecture of waveform rendering loops, marker anchor management systems, or Web Audio API routing networks unless explicitly instructed.
Preserve DSP Math: Symmetrically retain all trigonometric equations, Cubic Hermite Splines, Constant-Power Panning constraints, and zero-crossing detection routines within source files. A structural deviation of even a single sample (1\text{ sample}) constitutes a critical production failure.
Strict UI Alignment: All graphical modulations must cleanly conform to specified spatial layout grids, dimensions, and hex color tokens.
Zero Spurious Scrollbars: Prevent internal horizontal scrollbar generation inside the left Track Control Panel (TCP) container at all costs.

2. UI & Layout Refactoring Specifications

To eliminate vertical row desynchronization and layout overlaps during timeline scrubbing or zooming operations, all rendering passes must strictly conform to the following nested architecture:

2.1. Unified Row Layout — Fixing Vertical Misalignment

Strict Grid Containment: Independent scrolling columns for track controls and waveforms are strictly prohibited.
Row Lock: Every unique channel track must be bundled inside a single parent Unified Track Row container framework (Flex Row or Grid Row) enforcing a rigid vertical constraint (H = 96\text{ px}).
Single Scrollbar Mandate: The layout must expose exactly one global vertical scrollbar on the far right of the viewport container. This scrollbar controls the entire track stack workspace simultaneously, forcing the TCP decks and waveform canvas viewports to slide along the $Y$-axis in perfect physical synchronization.

2.2. Graphical Overlap Containment Mechanics

TCP Isolation: The left TCP channel block requires a rigid width lock at 300\text{ px}, flex-shrink: 0, and a solid background color (background-color: #262626). It must be explicitly configured with overflow: hidden to block internal horizontal overflow scrollbars.
Z-Index Layering: Assign an elevated layout layer profile (position: relative, z-index: 20) to the TCP column. When the right timeline area scrolls horizontally to the left, all waveform graphics, grid line divisions, and the absolute playback playhead line must scroll seamlessly beneath the solid TCP masking layer.

2.3. Dynamic Min-Zoom Constraint Specification

Viewport Boundary Alignment: When executing a macro zoom-out operation, the comprehensive project arrangement length—stretching from 0.00\text{ s} out to the termination milestone (T_{\text{max}})—must fit perfectly within the visible horizontal frame width (W_{\text{viewport}}).
Dynamic Bounds Calculation: The layout manager must dynamically calculate the bounding minimum scale factor (Z_{\text{min}}) before updating drawing buffers:

Z_{\text{min}} = \frac{W_{\text{viewport}}}{T_{\text{max}}}

Clamping Rule: Under no circumstances can the active zoom factor Z drop below the Z_{\text{min}} threshold. Enforcing this clamping boundary blocks the generation of dead black voids on the right side of shorter clips and prevents spurious scrollbar scaling artifacts.

3. Microscopic Viewport Waveform Painting (Ultra-Zoom Render Modes)

Whenever a user zooms deeply onto the timeline canvas to analyze microscopic phase movements, the canvas engine automatically swaps its calculation loop routines based on the instantaneous visible sample density profile (\text{samplesPerPixel}):

               SAMPLES PER PIXEL DENSITY SPECTRUM
   [Samples/px ≥ 4] ──────────────────────► Peak Waveform (Symmetrical Vertical Min/Max bars)
   [1.5 ≤ Samples/px < 4] ────────────────► Continuous Polyline (Light Cyan Sine Path)
   [Samples/px < 1.5] ────────────────────► Discrete Sample Nodes (Green Emerald Nodes + Polyline)

3.1. Peak Compression Mode (`\text{samplesPerPixel} \ge 4` — `image_5ec2e5.png`)

Waveform Envelopes: Renders a high-density, symmetrical downsampled waveform graphic. The engine reads localized segment buffers to connect absolute maximum (Max) and minimum (Min) sample peaks passing through identical pixel columns using clean vertical line strokes.

3.2. Single Continuous Polyline & Node Mode (`\text{samplesPerPixel} < 4`)

Continuous Polyline: Transitions away from vertical peak columns to compile a fine, anti-aliased single continuous vector polyline tracking raw values in professional cornflower blue (#5bc0be). The translation maps absolute sample addresses to physical drawing coordinates (X_i, Y_i):

X_i = \left( \frac{i}{f_s} \right) \times Z - \text{scrollLeft}, \quad Y_i = \text{mid}_Y + x[i] \cdot \left( \text{height} \times 0.42 \right)

Discrete Sample Nodes (\text{samplesPerPixel} < 1.5): Overlays luminous green emerald circle markers (#6ee7b7) with a rigid radius r = 2\text{ px} directly centered over every sample index coordinate (X_i, Y_i). To prevent GPU thread thrashing and rendering lag, point nodes are only drawn if the horizontal pixel spacing between adjacent nodes satisfies a \ge 4\text{ px} width threshold.
Logarithmic Amplitude Grid: Projects thin, low-contrast background horizontal marker grids to establish clear visible decibel tracking boundaries: a positive upper peak grid at +6.0\text{ dB} (or 0\text{ dBFS}), a true horizontal identity zero-line axis at -\infty\text{ dB} (0\text{V} absolute silence), and a negative lower sub-grid line at -6.0\text{ dB}.

4. Selection Ranges & Modifier Input Mechanics

4.1. Persistent Anchor Point Tracking Refs

State Preservation: To ensure that horizontal selection boundaries are never discarded or cleared when UI frameworks trigger background state refresh cycles, the coordinate calculation loops must persistently cache initial interaction milestones inside non-reactive memory Refs:
Main Session Workspace: Employs localSelectionAnchorRef to monitor channel track selections, and rulerAnchorRef to track global time loops on the ruler.
Sub-Tab Sandbox Workspace: Locks anchor coordinate data inside subTabAnchorRef.

4.2. Shift + Click Selection Range Adjustment Algorithm

When intercepting a primary mouse-down event (onMouseDown) where the Shift modifier is explicitly engaged (e.shiftKey === true), the tracking framework must execute the following sequence:

Event Interception: Immediately call e.preventDefault() and e.stopPropagation(). This blocks the thread, halting automatic playhead relocation or clip dragging sequences.
Anchor Extraction: Extract the absolute timestamp cached inside the target workspace Ref (T_{\text{anchor}}). If the reference object is unpopulated, write the active playback playhead timestamp (currentTime) to act as the fallback anchor milestone.
Boundary Translation: Convert the new cursor coordinate column pixel position into absolute timeline seconds to define the moving boundary marker (T_{\text{end}}).
Range Construction: Update the highlighted selection envelope parameters to encapsulate the full calculated interval:

\text{Selection Range} = [\min(T_{\text{anchor}}, T_{\text{end}}), \max(T_{\text{anchor}}, T_{\text{end}})]

4.3. Transport Loop Constraints & Escape Hook

Strict Loop Lock: When a selection window [T_{\text{start}}, T_{\text{end}}] is engaged alongside loop playback mode, the transport playhead can never drift past T_{\text{end}}. Upon reaching the T_{\text{end}} index, the audio thread must instantly trigger an immediate, gapless reset back to T_{\text{start}}.
Escape Hook: To clear selection boundaries and return the engine to standard non-repeating tracking, the user executes a Ctrl + Click shortcut combo over an unpopulated workspace area. Once the selection ranges are nullified, pressing the Spacebar drives continuous, linear playback past the old loop constraints.

5. Non-Linear Graphical Automation Envelopes

The application upgrades static, linear layout components using the following signal processing algorithms:

5.1. Volume Automation Spline (Monotone Cubic Hermite Spline)

To connect peach-colored volume nodes smoothly without inducing artificial overshoot peaks, the system runs a 3rd-order monotone cubic interpolation framework:

y(t) = (2t^3 - 3t^2 + 1)y_1 + (t^3 - 2t^2 + t)h \cdot m_1 + (-2t^3 + 3t^2)y_2 + (t^3 - t^2)h \cdot m_2

Where h = t_2 - t_1, and the localized tangents (m_1, m_2) are evaluated via the Fritsch-Carlson configuration method to preserve strict mathematical monotonicity across the curve.

5.2. Boundary Fade Contours (Trigonometric Cosine S-Curve)

The physical curvature profile of the deep red fade envelopes is derived via trigonometric functions to protect structural transient integrity at the clips boundaries:

f_{\text{in}}(t) = \frac{1 - \cos\left( \pi \cdot \frac{t}{L_{\text{fade}}} \right)}{2}, \quad f_{\text{out}}(t) = \frac{1 + \cos\left( \pi \cdot \frac{t - (T_{\text{max}} - L_{\text{fade}})}{L_{\text{fade}}} \right)}{2}

5.3. Constant-Power Stereo Panning Law

To eliminate spatial perceived volume collapse (Center Dip) when moving signals across Left (L) and Right (R) drivers, the cumulative output sound field energy must remain perfectly preserved at unity (1.0) across all panning trajectories:

\theta(t) = \frac{p(t) + 1}{2} \cdot \frac{\pi}{2}, \quad g_L(t) = \cos(\theta(t)), \quad g_R(t) = \sin(\theta(t))

6. Isolated Sandbox Sub-Tab Workspace & Synchronization

When a user double-clicks an audio clip asset or highlights a segment and selects "Edit in Sub-tab", the application triggers a specialized editing sandbox pipeline:

6.1. Sandbox Isolation Flow

Buffer Isolation: The application isolates a non-destructive copy of the targeted sample slice (Audio Sub-segment Buffer) into memory and spawns a distinct standalone document editor window. The timeline measuring ruler inside this sub-tab resets completely to map t = 0.0\text{ s} at its origin.
Row Scale Adjustments: Users drag the bottom perimeter boundary of the single track lane (ns-resize style handle) to dynamically alter height constraints between a lower boundary of 48\text{ px} and an upper boundary of 200\text{ px} for precision envelope drawing.

Normalize Ceiling: Evaluates the signal array to scale the single maximum absolute sample peak exactly up to user-specified decibel thresholds variable from -12\text{ dBFS} to 0\text{ dBFS}.
Gain & Pitch Modulation: Adjusts macro channel decibel levels and transposes fundamental vocal or instrument frequencies using an integrated Phase Vocoder algorithm.
Speed Stretch Slider (%): Drives time-stretching operations visuals directly from the timeline layer by holding the Alt modifier key and dragging the rightmost bounding clip handle. A bright yellow metadata text string (e.g., Speed: 75.0%) renders at the upper-left boundary of the audio clip container:

S = \frac{D_{\text{original}}}{D_{\text{stretched}}} \times 100\%

6.3. Volume Pencil Automation Tool

Activating the Pencil drawing utility overlays a solid horizontal neon green line representing 0\text{ dB} (Unity Gain) across the track axis. Users left-click to drop custom vector control points, dragging node handles upward to boost signal gains (up to +3\text{ dB}) or downward to attenuate track volume (down to -30\text{ dB}).

6.4. Crossfaded In-Place Overwrite Core Loop (Apply & Sync-Back)

Clicking the Apply action pushes the processed sample buffer array back into the primary multitrack mixing arrangement canvas. To prevent wave phase breakage that precipitates popping artifacts, the splicing engine bakes an ultra-fast linear crossfade envelope (w = 10\text{ ms}) across both the initial and trailing splice boundaries:

\text{Output}(t) = (1 - \alpha(t)) \cdot \text{Original}(t) + \alpha(t) \cdot \text{Edited}(t - T_{\text{start}})

7. Automated AI Loop Scanning & Fade-Free Slicing

7.1. Chromagram-Driven AI Loop Indexing

The system processes raw track files using an asynchronous Celery worker script that compiles a Self-Similarity Matrix (SSM) derived from spectral Chroma audio features. The algorithm locates areas showcasing the highest recurrence metrics (e.g., drum grooves, chord loops) and automatically maps matching timeline markers onto the user interface canvas views.

7.2. Sample-Accurate Phase Inversion Slicing (Fade-Free AI Cut)

Artificially introducing volume fade envelopes to mask clicking anomalies during macro audio cuts is strictly prohibited due to its destructive impact on percussive transient impact waves. The system must natively locate the absolute closest physical zero-crossing address where the signal array crosses the zero baseline (absolute silent index):

x[i] \cdot x[i+1] \le 0

Once both clip perimeters are hard-aligned to true zero-amplitude sample offsets, the engine slices the raw binary array inside RAM and generates a new track row directly below, dropping the processed clip onto it at the exact optimized time coordinates.

8. Dockerized Python Server Deployment & Architecture

8.1. Headless JUCE C++ VST/VSTi Audio Rendering Pipeline

To ensure that containerized Python workflows can initialize and instantiate VST3 processing nodes and virtual instruments compiled via C++ (JUCE framework) under Linux environments without triggering X11 display linkage initialization crashes, the underlying systems architecture must embed and initialize a virtual display frame buffer (Xvfb):

# Dockerfile snippet installing core graphical rendering dependencies and Xvfb
RUN apt-get update && apt-get install -y \
    libgl1-mesa-glx libglu1-mesa libasound2 libjack-jackd2-0 \
    libfreetype6 libfontconfig1 libx11-6 libxext6 libxrandr2 \
    xvfb \
    && rm -rf /var/lib/apt/lists/*

ENV DISPLAY=:99

CMD ["sh", "-c", "Xvfb :99 -screen 0 1024x768x16 & python app/main.py"]

8.2. RBAC Security, Disk Quotas, and Feature Flags Configuration

First-Login Security Control (Enforced Password Reset): System administrator accounts are initialized using parameters parsed from environment strings (DEFAULT_ADMIN_PASSWORD). The identity route mapper assigns a strict boolean cờ must_change_password = True value, which intercepts all subsequent incoming client API audio processing requests and returns a HTTP 403 Forbidden error loop until a secure password overwrite is completed.
Storage Allocation Constraints (Admin Quotas): The gateway layer embeds a resource allocation supervisor tracking storage disk boundaries (S_{\text{limit}}). It aggregates the byte sizes of active array blocks before certifying a file upload sequence:

S_{\text{used}} + S_{\text{new}} \le S_{\text{limit}}

Feature Flags Management: Administrators can dynamically enable or disable advanced server-side runtime pipelines (such as high-fidelity 24-bit WAV mixdown rendering or automated AI track generation) via modifications to global database flag keys.

16 KiB Raw Blame History