# Technical Specification: Advanced Editing Toolset & Graph-Based Continuous Waveform Painting on Sub-Tab

This document defines the interactive layout design, the configuration of the toolbar button arrays, and the signal processing routines for compiling a Graph-based Continuous Waveform graph optimized for the microscopic viewports inside the isolated temporary document workspace (Sub-tab), referencing the structural paradigms of `image_5ec2e5.png` and `image_5ec363.png`.

---

## 1. Target Selection Scope

The toolset within the Sub-tab environment supports two target operational boundaries:

* **Global Clip:** When no specific timeline selection highlighted mask is present, all active DSP effects apply uniformly across the entire length of the extracted Audio Clip.
* **Selected Range:** When an explicit timeline segment $[T_{\text{start}}, T_{\text{end}}]$ is highlighted by the user, DSP routines calculate changes exclusively inside those boundaries. Splice junctions automatically compute crossfades to mitigate transient click/pop anomalies.

---

## 2. Ruler-Based Tools

These utilities display as intuitive, linear slider scales (Sliders/Rulers) embedded in the top toolbar row:

```text
[ Normalize: |======o======| 0 dB ]  [ Gain: |====o====| +3 dB ]  [ Pitch: |==o==| -2 Semi ]

```

### 2.1. Peak Normalization

* **UI Layout:** A slide scale control allowing users to configure target amplitude thresholds variable from $-12\text{ dBFS}$ down to $0\text{ dBFS}$.
* **DSP Math Algorithm:** Locate the maximum absolute peak amplitude value $A_{\text{max}}$ within the targeted area, then multiply all active samples by a static scalar gain multiplier $G$:

$$G = \frac{10^{\frac{\text{Target\_dB}}{20}}}{A_{\text{max}}}$$



### 2.2. Volume Up / Down (Quick Gain)

* **UI Layout:** A linear sliding ruler modulating the overall absolute gain structure of the focused segment.
* **Operational Range:** Adjustable from $-\infty\text{ dB}$ (complete mute attenuation) up to $+12\text{ dB}$ of linear amplification.

### 2.3. Pitch Shifting

* **UI Layout:** A calibrated slider modifying the project's fundamental frequencies discrete in semitones or cents.
* **Operational Range:** Boundaries map from $-12\text{ semitones}$ (one octave down) to $+12\text{ semitones}$ (one octave up).
* **DSP Engine Routine:** Employs a spectral Phase Vocoder to shift frequencies without affecting the physical, real-time duration layout of the segment.

---

## 3. Graph-Based Fades

Fading curves overlay graphically directly onto the highlighted waveform canvas region, enabling precise boundary amplitude adjustments:

```text
          Linear Fade-In                         Exponential Fade-Out
   +───────────────────────────+             +───────────────────────────+
   |           /███████████████|             |███████████\               |
   |         /  ███████████████|             |███████████  \             |
   |       /    ███████████████|             |███████████    \___        |
   |     /      ███████████████|             |███████████         \______|
   +───────────────────────────+             +───────────────────────────+
   |<──────── Fade-In ────────>|             |<─────── Fade-Out ────────>|

```

* **Fade-In:** Multiplies an ascending amplitude ramp from $0.0$ to $1.0$ at the starting index profile of the selection region. Users can toggle seamlessly between **Linear** or **Exponential** curves to achieve a smoother, more psychoacoustically natural volume build-up.
* **Fade-Out:** Multiplies a descending amplitude decay ramp from $1.0$ down to $0.0$ at the trailing boundary edge of the selection range.

---

## 4. Ruler Percentage Stretch Tool

A dedicated percentage metric scale control (`Ruler %`) sitting on the control toolbar dictates time-stretching and playback velocity parameters:

```text
[ Speed Stretch %: |========o========| 100% (Native) ] -> Range: 50% - 200%

```

* **Interaction Mapping:** Users drag the percentage slider node or hold down the `Alt` key and drag the rightmost boundary edge of the clip along the horizontal axis to change this scale metric.
* **Sync Formula:** Let $D$ map to the unscaled native duration value, and $D'$ map to the target modified duration footprint. The resulting structural playback speed ratio percentage ($S$) is given by:

$$S = \frac{D}{D'} \times 100\%$$



---

## 5. Continuous Graph-Based Waveform Painting & Microscopic Viewports

The waveform graph inside the Sub-tab is compiled as a unified, continuous line vector (Continuous Line Graph) that flows seamlessly along the timeline axis, mapping the literal physical phase displacements of the underlying audio signal.

### 5.1. Logarithmic Amplitude Axis Grid Layout

Following the professional paradigm established in `image_5ec2e5.png`, the waveform painting canvas is divided by a symmetrical layout grid reflecting both positive and negative polarity limits of the central horizontal axis:

```text
  +6.0 dB ───────────────────────────────────────────────────────────────────
           ~ ~ ~ ~ ~ ~ ~ ~ (Sub-division Grid Line) ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
  -6.0 dB ───────────────────────────────────────────────────────────────────
           \             /             \             /             \
  -Inf dB  ─○───────────/───────────────○───────────/───────────────○───────── (Zero-Line Axis)
             \         /                 \         /                 \
  -6.0 dB ───────────────────────────────────────────────────────────────────
  +6.0 dB ───────────────────────────────────────────────────────────────────

```

* **Visual Bounding Thresholds:**
* **Central Zero Axis (-Inf. dB):** Maps the absolute baseline $0\text{V}$ electrical reference (complete absence of audio signal / absolute silence).
* **Symmetrical Decibel Grids:** Project accurate scale metrics tracking normalized peak levels (the inner $-6.0\text{ dB}$ sub-grid marks a $50.1\%$ amplitude ceiling, while the outermost physical frame boundary aligns to $+6.0\text{ dB}$ or $0\text{ dBFS}$).



### 5.2. Standard Workspace View vs. Ultra Zoom Viewport Scaling

The drawing engine dynamically hot-swaps its rendering calculations (Rendering Routine) depending on the active pixel compression metric $Z$ (pixels/second):

* **Standard View Mode ($Z < 500\text{ pixels/second}$):** The system deploys a structural peak compression layout algorithm (**Peak Waveform**—as referenced in `image_5ec2e5.png`). It connects the maximum absolute upper peak bounding indices (Max) with the lower minimum value ranges (Min) passing through a common pixel column into a unified vector line, generating an organic, aliases-free continuous waveform silhouette.
* **Micro Viewport Zoom-In ($Z \ge 500\text{ pixels/second}$—as referenced in `image_5ec363.png`):** Once viewport stretching scales past this threshold, the framework transitions into a **Single Continuous Sine Polyline** loop. Chronologically sequential acoustic sample addresses ($x[i]$, $x[i+1]$) map as discrete vector coordinate indices bound together by thin lines (using sharp smooth polyline vectors or linear/cubic spline interpolation loops), charting pristine, individual sinusoidal phases explicitly.

### 5.3. Zero-Crossing Alignment within Ultra Zoom Viewports

When performing rapid cursor tracking edits (Scrub/Drag Selection), the alignment routine locks the selection boundary marker coordinates onto the nearest baseline sample offset exhibiting a complete algebraic phase conversion (sign inversion):


$$x[i] \cdot x[i+1] \le 0$$

---

## 6. Top Duration Timeline

Directly above the isolated sub-tab waveform canvas lane, a dedicated horizontal measuring ruler tracks clip timing data:

```text
   | 0:00.000    | 0:01.000    | 0:02.000    | 0:03.000    | 0:04.000 (Duration: 4.152s)
   +───────────────────────────────────────────────────────────────────────────────────────+
   | [==================== VÙNG QUÉT CHỌN (RANGE SELECTION) ====================]          |
   +───────────────────────────────────────────────────────────────────────────────────────+

```

* **Total Duration Monitoring:** Renders the absolute, precise time extent of the isolated audio block in the right-hand corner of the timeline ruler layout (e.g., `Duration: 12.450s`).
* **Duration Selection Drag:** Left-clicking and dragging horizontally inside this top duration bar defines a highlighted selection overlay window. This range indicator automatically projects down into the waveform lane underneath.

---

## 7. Bottom Transport Panel & Master Tools

A comprehensive control framework containing expanded navigation buttons and deep session processing controls anchors the bottom row of the sub-tab environment, matching the layout structure in `image_5ec2e5.png`:

```text
+─────────────────────────────────────────────────────────────────────────────────────────────+
|  [● Rec]  [◀◀ Back]  [▶ Play]  [|| Pause]  [■ Stop]  |  Rate: |====o====| 0.00  |  Loop: [X]  |
|---------------------------------------------------------------------------------------------|
|  [Volume Pencil Tool]  [AI Analysis Tool]  | Active Asset: linh_ngua_powerup.wav            |
+─────────────────────────────────────────────────────────────────────────────────────────────+

```

### 7.1. Functional Mapping Matrix:

* **Record (● Red Indicator):** Drives live microphone capture sequences targeted straight into the isolated sub-tab data matrix.
* **Back (◀◀ Rewind):** Resets the timeline playhead position index back to the absolute starting point ($t = 0.0\text{ s}$).
* **Play / Pause / Stop:** Coordinates low-latency runtime audio execution tracking locked onto the sub-tab's RAM cache blocks.
* **Rate Slider:** Adjusts the global monitoring playback pitch speed metrics in real time without overwriting source asset length (calibrated step ranges variable from `-1.00` scaling up to `+1.00`).
* **Loop Toggle:** Toggles continuous cycle loops over the highlighted section or the whole clip.
* **Volume Pencil Tool:** Engages the drawing framework to map point nodes for automated amplitude envelopes.
* **AI Analysis Tool:** Instructs the dockerized engine to evaluate rhythmic transient markers and pitch tracking grids.

---

## 8. Volume Automation Envelope (Pen Tool)

This advanced timeline automation layer allows audio designers to draw custom gain curves over the background waveform graphics.

```text
                  VOLUME AUTOMATION ENVELOPE (PEN TOOL)
   +3 dB ──────────────────────────────────────────────────────────────
         \      Node 1                                  Node 3
          \      ○                                       ○
   0 dB ───\────/─\─────────────────────────────────────/─\─────────── (0 dB Unity Gain Axis)
            \  /   \                                   /   \
             \/     \                                 /     \
              ○      \_______________________________/       \________
            Node 2                                            Node 4
  -30 dB ──────────────────────────────────────────────────────────────
   |<─────────────────── Horizontal Axis (Time) ─────────────────────>|

```

### 8.1. Pen Tool Interaction Mechanics

* **Activation:** Clicking the designated Pencil Tool icon in the control panel modifies the pointer device presentation into a pencil graphic.
* **Envelope Initialization:** Activating the Pen Tool generates a solid horizontal neon green line representing $0\text{ dB}$ (Unity Gain) across the track workspace, acting as the baseline master axis.
* **Drawing Automation Curves:**
* Left-clicking anywhere along this line creates an adjustable anchor point (**Control Node**).
* Dragging an initialized control node upward increases signal amplitude (up to a maximal ceiling boundary of $+3\text{ dB}$).
* Dragging a control node downward reduces signal amplitude (down to a lower attenuation floor of $-30\text{ dB}$).
* The graphics framework automatically updates straight vector paths between sequential nodes utilizing simple linear interpolation.



### 8.2. DSP Volume Envelope Math

Given two chronologically adjacent drawn points $P_1(t_1, V_1)$ and $P_2(t_2, V_2)$, the targeted instantaneous decibel gain variable $V_{\text{dB}}(t)$ at an arbitrary time index $t$ ($t_1 \le t \le t_2$) matches the following linear equation:


$$V_{\text{dB}}(t) = V_1 + (t - t_1) \cdot \frac{V_2 - V_1}{t_2 - t_1}$$

This decibel value must be translated into a standard linear gain scalar coefficient $G_{\text{linear}}(t)$ to multiply it into the core audio sample stream values:


$$G_{\text{linear}}(t) = 10^{\frac{\text{V}_{\text{dB}}(t)}{20}}$$

$$x_{\text{automation}}[n] = x[n] \cdot G_{\text{linear}}\left( \frac{n}{\text{Sample Rate}} \right)$$

---

## 9. Porting Guidelines for Python Desktop Layouts (PyQt6 QPainter Context)

When translating the polyline vector engine and the symmetrical decibel gridding lines into a containerized desktop application using the native `QPainter` canvas inside PyQt6, leveraging a structured `QPainterPath` prevents rendering lag when mapping high-density signal segments:

```python
# [PYTHON PORTING BLUEPRINT] - Continuous Polyline Waveform Rendering via QPainterPath
from PyQt6.QtGui import QPainter, QPainterPath, QPen, QColor
from PyQt6.QtCore import QPointF, Qt
import numpy as np

def paint_continuous_waveform_path(painter: QPainter, rect_width: int, rect_height: int, y: np.ndarray, zoom_level: float):
    """
    Renders a unified continuous single polyline path tracing absolute physical signal transitions.
    y: A 1D NumPy float32 array tracking raw sample amplitudes bounded within [-1.0, 1.0].
    zoom_level: The scale allocation mapping physical drawing pixels per second of audio data.
    """
    if len(y) == 0:
        return
        
    painter.setRenderHint(QPainter.RenderHint.Antialiasing, True)
    mid_y = rect_height / 2.0
    
    # 1. Compile background Decibel reference grids (-6.0 dB, -Inf. dB, -6.0 dB)
    grid_pen = QPen(QColor(45, 45, 45), 1, Qt.PenStyle.DashLine)
    painter.setPen(grid_pen)
    
    # A threshold of -6.0 dB maps approximately to an absolute scalar amplitude index of 0.501
    y_6db_top = mid_y - (0.501 * (rect_height * 0.42))
    y_6db_bottom = mid_y + (0.501 * (rect_height * 0.42))
    
    painter.drawLine(0, int(y_6db_top), rect_width, int(y_6db_top))
    painter.drawLine(0, int(y_6db_bottom), rect_width, int(y_6db_bottom))
    
    # Paint the absolute Zero-Line horizontal center axis (-Inf. dB)
    center_pen = QPen(QColor(60, 60, 60), 1, Qt.PenStyle.SolidLine)
    painter.setPen(center_pen)
    painter.drawLine(0, int(mid_y), rect_width, int(mid_y))
    
    # 2. Initialize the Continuous Vector Polyline Route Layout Block
    wave_path = QPainterPath()
    wave_pen = QPen(QColor(100, 149, 237), 1.2, Qt.PenStyle.SolidLine) # Professional Cornflower Blue
    painter.setPen(wave_pen)
    
    # Map raw buffer indexes into structural coordinate pixels
    start_point_set = False
    for x_pixel in range(rect_width):
        # Translate current canvas pixel offset back to timeline seconds metrics
        time_at_pixel = x_pixel / zoom_level
        
        # Calculate target array element offset
        sample_index = int(time_at_pixel * 44100) # Assuming project sample rate baseline at 44.1kHz
        if sample_index >= len(y):
            break
            
        amplitude = y[sample_index]
        y_pixel = mid_y + (amplitude * (rect_height * 0.42))
        
        if not start_point_set:
            wave_path.moveTo(float(x_pixel), y_pixel)
            start_point_set = True
        else:
            wave_path.lineTo(float(x_pixel), y_pixel)
            
    # Draw the continuous vector polyline overlay onto the viewport canvas
    painter.drawPath(wave_path)

```