Technical Specification: Tabbed Interface, Configurations & Strict Looping Constraints

This document details the software design specification for the tabbed multi-project structure, top-level application configurations, and low-latency transport loop engine boundaries for SonicForge Studio, referencing the professional DAW layout in image_e0e462.png.

1. Multi-Tab Architecture: Main vs. Sub (Temporary) Tabs

As illustrated in image_e0e462.png (indicated by the red arrows pointing to the tab bar), the application supports multiple active document spaces running in parallel.

+---------------------------------------------------------------------------------+
| File  Edit  View  Insert  Track  Options  Actions  Extensions  Help            |
+---------------------------------------------------------------------------------+
| [*Main_Session.rpp] | [Sub_Tab_Isolated_Edit] |                                 |
+-----------------------------------------+---------------------------------------+
|                                         |                                       |
|  [Main Tab: Multitrack Workspace]       |  [Sub Tab: Isolated Sample Editor]    |
|   - Multi-channel arrangements          |   - Destructive audio processing      |
|   - Level mixing & panning              |   - Focus on selected sub-region      |
|   - Real-time plugin chains             |   - Apply specialized DSP / AI        |
|                                         |                                       |
+-----------------------------------------+---------------------------------------+

1.1. Main Tab (Multitrack Mixing)

Scope: Hosts the global arrangement canvas with multiple tracks stacked vertically.
Function: Used for complex operations including track leveling, master mixdowns, track synchronization, and timeline-based multi-channel volume automation.

1.2. Sub Tab (Temporary Isolated Clip Editor)

Scope: A sandbox workspace containing only the isolated audio buffer extracted from a specific track's selection clip.
Function: Contains standard sample-level editing tools (trimming, phase inversion, amplification, and precision AI noise reduction).
Workflow Sync:
Modifying data inside the Sub Tab operates on a temporary audio buffer.
Clicking Apply triggers a non-destructive or destructive overwrite back into the Main Tab's parent track at the exact source offset coordinates.

To support both basic user preferences and deep AI/system configurations, a global Menu Bar is placed at the absolute top of the frame (matching the menu path: File Edit View Insert Item Track Options Actions Extensions Help in image_e0e462.png).

2.1. Configuration Architecture

These menus map directly to local configurations and server APIs on the Docker backend:

File: Session operations (New, Open, Save Session) and Offline Audio Mixdown export settings (Sample Rate, Bit-Depth, Format).
Options -> Audio Device Settings: Defines client/server hardware routing, sample buffer frame size (64 \rightarrow 512 samples) to control playback latency, and audio API endpoints (ASIO, CoreAudio, ALSA).
Options -> AI Integration Settings:
Endpoint Configuration: Sets API Gateway URLs (OpenAI-compatible server endpoint).
Authentication: API keys, model parameters, and target model configurations (e.g., gpt-4o-mini, local ollama endpoints).
Actions -> Admin Dashboard: Admin-only access panel to manage user accounts, disk quota limits (S_{\text{limit}}), active socket connections, and toggle system Feature Flags.

3. Playhead Tracking & Looping Synchronicities

The transport engine must manage low-latency coordinate translations to ensure the playhead red line exactly mirrors the hardware audio clocks during loop operations.

3.1. Looping Playhead Movement Logic

Seamless Loop Synchronization: When loop play is triggered, the playhead coordinates on the visual timeline must instantly align with the active audio buffers.
Immediate Reset on Cycle: When the current audio timestamp t reaches the loop end point T_{\text{end}}, the playhead must immediately reset to the loop start point T_{\text{start}} without lagging or disappearing from the viewport.
Visual Refresh Coordination: The browser animation loop (requestAnimationFrame) or Python GUI timer must query the audio hardware clock directly, avoiding UI-driven clock drift:

t_{\text{playhead}} = T_{\text{start}} + \left( (t_{\text{system}} - t_{\text{trigger}}) \pmod{T_{\text{end}} - T_{\text{start}}} \right)

4. Strict Playhead Looping Constraints & Escape Mechanism

         Strict Loop State Locked (Spacebar toggles within boundary)
         +-------------------------------------------------+
         |                                                 |
         ▼                                                 | (Loop Repeat)
   [ T_start ] ==============> [ Playhead (t) ] ======> [ T_end ]
         │
         │  (User clicks outside selection region)
         ▼
   [ Escape Loop Triggered ]
         │
         ▼  (Press SPACEBAR)
   [ Linear Playback Active ] ===> Playhead continues past T_end indefinitely

4.1. Strict Boundary Constraint (Active Loop)

When a time selection [T_{\text{start}}, T_{\text{end}}] is active and looping is turned on, the playhead is locked to the interval:

t \in [T_{\text{start}}, T_{\text{end}}]

Under no circumstances can the playhead drift past T_{\text{end}}. If the audio thread finishes rendering the buffer slice corresponding to T_{\text{end}}, it must seamlessly jump back to T_{\text{start}}.

4.2. Escape Loop Mechanism

To leave the loop and return to continuous, non-repeating playback, the user must perform the following actions:

Clear Selection Focus: The user clicks outside the selection box on an empty area of the timeline ruler or track lane.
Deregister Selection Boundaries: The variables T_{\text{start}} and T_{\text{end}} are cleared (set to null or 0 and T_{\text{max}} respectively).
Resume Linear Playback: Pressing the Spacebar key triggers the transport to play continuously through and past the old boundary marker.

4.3. Keyboard Mapping Matrix (Python GUI Translation)

# PyQt6 / PySide6 Key Event Hook Simulation

def keyPressEvent(self, event):
    if event.key() == Qt.Key.Key_Space:
        if self.transport.is_playing:
            self.transport.pause()
        else:
            # If selection was cleared, it continues linear playback past T_end
            if self.session.selection_cleared:
                self.transport.play_linear(from_time=self.playhead.current_time)
            else:
                self.transport.play_looped(
                    start=self.session.selection_start, 
                    end=self.session.selection_end
                )

6.9 KiB Raw Blame History