# 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. ```text +---------------------------------------------------------------------------------+ | 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. --- ## 2. Top-Level Menu Bar & Application Configurations 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 ```text 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: 1. **Clear Selection Focus:** The user clicks outside the selection box on an empty area of the timeline ruler or track lane. 2. **Deregister Selection Boundaries:** The variables $T_{\text{start}}$ and $T_{\text{end}}$ are cleared (set to `null` or $0$ and $T_{\text{max}}$ respectively). 3. **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) ```python # 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 ) ```