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 ```