Dưới đây là toàn bộ nội dung tài liệu đặc tả kỹ thuật đã được chuyển đổi sang định dạng Markdown chuẩn, tối ưu hóa các khối mã nguồn (`python`, `text`), căn chỉnh bảng biểu, sơ đồ luồng ASCII và các công thức toán học dạng LaTeX:

# Technical Specification: Sub-Tab Audio Clip Editor & DSP Operations

This document outlines the software engineering specification for the temporary isolated Sub-Tab Audio Clip Editor. It defines internal clipboard mechanics, DSP algorithms for selection-based operations, Context Menu structures, and main application menu shortcuts.

---

## 1. Clipboard & Cursor-Aligned Insertion Mechanics

The Sub-Tab workspace features an isolated, low-latency stereo/mono audio buffer. The editor tracks a local virtual playhead position $t_{\text{cursor}}$ and handles clipboard buffers using non-destructive splicing techniques.

```text
                  Local Timeline Buffer
+-------------------------------------------------------+
|  Track Waveform Segment       │                       |
+-------------------------------┼-----------------------+
                                ▲
                          t_cursor (Insertion Point)
                                │
                                ▼ [ PASTE TRIGGERED ]
+-------------------------------------------------------+
|  Track Waveform Segment       │ CLIPBOARD DATA │      |
+-------------------------------------------------------+
                                 ◄──────────────►
                                   clip_duration

```

### 1.1. Cursor Paste Action

When a paste command is issued (either via Context Menu, Application Menu, or Hotkey):

* **Payload Extraction:** Retrieve the copied `AudioBufferSegment` from the system/application clipboard.
* **Splicing Boundary Calculations:** Slice the current active timeline buffer at $t_{\text{cursor}}$.
* **Re-allocation & Stitching:**
* Compute the new duration: $T_{\text{new}} = T_{\text{original}} + T_{\text{clipboard}}$.
* Allocate a new virtual audio array $Y_{\text{new}}$:



$$Y_{\text{new}}(t) = \begin{cases} Y_{\text{original}}(t) & 0 \le t < t_{\text{cursor}} \\ Y_{\text{clipboard}}(t - t_{\text{cursor}}) & t_{\text{cursor}} \le t < t_{\text{cursor}} + T_{\text{clipboard}} \\ Y_{\text{original}}(t - T_{\text{clipboard}}) & t_{\text{cursor}} + T_{\text{clipboard}} \le t \le T_{\text{new}} \end{cases}$$

* **Playhead Update:** Advance the active playhead $t_{\text{cursor}}$ immediately to $t_{\text{cursor}} + T_{\text{clipboard}}$.

---

## 2. Selection Context Menu & DSP Engine

Right-clicking inside a highlighted region $[T_{\text{start}}, T_{\text{end}}]$ of the Waveform Canvas triggers an overlay context menu containing the following DSP and editing commands.

```text
+---------------------------------------------+
| Selection: [ 01:02.100 - 01:05.400 ]        |
+---------------------------------------------+
|  Normalize Selection To Peak                |
|  Adjust Gain/Volume...                      |
|  Adjust Panning (Stereo Balance)...         |
|  Fade In (Linear/Exponential)               |
|  Fade Out (Linear/Exponential)              |
|---------------------------------------------|
|  Cut                                 Ctrl+X |
|  Copy                                Ctrl+C |
|  Paste                               Ctrl+V |
|  Delete Selected Segment                Del |
|---------------------------------------------|
|  Loop Selection: [ ▲ ] [ 4 ] [ ▼ ] times    |
+---------------------------------------------+

```

### 2.1. Normalize Selection

Scales the peak amplitude of the selected segment to a target ceiling $A_{\text{target}}$ (defaulting to $1.0$ or $0\text{ dBFS}$):

$$Y_{\text{norm}}(t) = Y(t) \cdot \frac{A_{\text{target}}}{\max_{u \in [T_{\text{start}}, T_{\text{end}}]} \vert{}Y(u)\vert{}} \quad \text{for } t \in [T_{\text{start}}, T_{\text{end}}]$$

### 2.2. Volume (Gain dB) Adjustment

Applies a static linear gain multiplier derived from user-specified decibel scaling values ($\Delta\text{dB}$):

$$G = 10^{\frac{\Delta\text{dB}}{20}}$$

$$Y_{\text{gained}}(t) = Y(t) \cdot G \quad \text{for } t \in [T_{\text{start}}, T_{\text{end}}]$$

### 2.3. Panning (Stereo Balance)

Applies a constant-power panning law across Left ($L$) and Right ($R$) channels based on the panning angle $\theta \in [0, \pi/2]$, where $\theta = \pi/4$ represents absolute center:

$$Y_L(t) = Y_{\text{mono}}(t) \cdot \cos(\theta), \quad Y_R(t) = Y_{\text{mono}}(t) \cdot \sin(\theta)$$

### 2.4. Fade-In and Fade-Out (Linear / Exponential)

* **Linear Fade-In Curve:**

$$f_{\text{in}}(t) = \frac{t - T_{\text{start}}}{T_{\text{end}} - T_{\text{start}}} \quad \text{for } t \in [T_{\text{start}}, T_{\text{end}}]$$

* **Linear Fade-Out Curve:**

$$f_{\text{out}}(t) = 1.0 - \frac{t - T_{\text{start}}}{T_{\text{end}} - T_{\text{start}}} \quad \text{for } t \in [T_{\text{start}}, T_{\text{end}}]$$

### 2.5. Delete, Cut, and Copy

* **Delete:** Erases the selected segment $[T_{\text{start}}, T_{\text{end}}]$ and shifts all subsequent samples leftward.
* **Cut:** Copies the selected samples to the clipboard, then executes the *Delete* routine.
* **Copy:** Writes the targeted buffer segment to the clip memory without modifying the timeline.

### 2.6. Segment Looping with Step Multiplier

Repeats the selected segment $[T_{\text{start}}, T_{\text{end}}]$ consecutively $N$ times. The menu provides a numeric spinner (Up/Down buttons) to adjust $N$:

1. Extract segment: $Y_{\text{segment}} = Y(t)$ for $t \in [T_{\text{start}}, T_{\text{end}}]$.
2. Compute new duration adjustment: $\Delta L = (N - 1) \cdot (T_{\text{end}} - T_{\text{start}})$.
3. Duplicate and insert $Y_{\text{segment}}$ array $N-1$ times directly after $T_{\text{end}}$.

---

## 3. Global Menu Bar & Keyboard Shortcut Matrix

All context-dependent sub-tab actions are mapped directly to the global Menu Bar at the top of the DAW window, as specified in `image_e0e462.png`.

```text
File  Edit  View  Insert  Track  Options  Actions  Extensions  Help
       │
       ├── Normalize Selection  [Ctrl+Alt+N]
       ├── Adjust Volume...     [V]
       ├── Adjust Panning...    [P]
       ├── Fade In              [F]
       ├── Fade Out             [G]
       ├── Cut                  [Ctrl+X]
       ├── Copy                 [Ctrl+C]
       ├── Paste                [Ctrl+V]
       ├── Delete               [Del]
       └── Loop Clip...         [Ctrl+L]

```

### 3.1. Keyboard Mapping Table

To maximize speed and accessibility, the system listens for global key event hooks within the Sub-Tab window focus:

| Action Command | Main Menu Category | Recommended Keyboard Shortcut | Python Event Trigger (`QKeyEvent`) |
| --- | --- | --- | --- |
| **Cut** | Edit -> Cut | `Ctrl + X` | `Qt.Key.Key_X` + `ControlModifier` |
| **Copy** | Edit -> Copy | `Ctrl + C` | `Qt.Key.Key_C` + `ControlModifier` |
| **Paste** | Edit -> Paste | `Ctrl + V` | `Qt.Key.Key_V` + `ControlModifier` |
| **Delete** | Edit -> Delete | `Del` / `Backspace` | `Qt.Key.Key_Delete` / `Key_Backspace` |
| **Normalize** | Actions -> Normalize | `Ctrl + Alt + N` | `Qt.Key.Key_N` + `ControlModifier` + `AltModifier` | 
| **Fade In** | Actions -> Fade In | `F` | `Qt.Key.Key_F` |
| **Fade Out** | Actions -> Fade Out | `G` | `Qt.Key.Key_G` |
| **Loop Segment** | Actions -> Loop... | `Ctrl + L` | `Qt.Key.Key_L` + `ControlModifier` |
| **Adjust Volume** | Actions -> Gain... | `V` | `Qt.Key.Key_V` |
| **Adjust Panning** | Actions -> Panning... | `P` | `Qt.Key.Key_P` |

---

## 4. Python Implementation Notes for Docker Server Porting

When porting these sub-tab operations to your Python DSP engine (`core/audio_editor.py`), use NumPy slice vectors to perform non-destructive edits on waveforms:

```python
# Prototype helper for non-destructive volume adjustment in Python
import numpy as np

def apply_gain_on_segment(y: np.ndarray, sr: int, start_sec: float, end_sec: float, gain_db: float) -> np.ndarray:
    """
    Applies gain in dB to a selected segment of a mono numpy audio array.
    """
    # 1. Translate time coordinates securely with boundary checking
    start_sample = max(0, int(start_sec * sr))
    end_sample = min(len(y), int(end_sec * sr))
    
    # 2. Convert dB value to linear multiplier
    multiplier = 10.0 ** (gain_db / 20.0)
    
    # 3. Create a deep copy and modify segment in-place
    y_edited = np.copy(y)
    y_edited[start_sample:end_sample] *= multiplier
    
    return y_edited

```