# 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
                )

```