Files

T

3dtours d5143b440a fix: change md files to md folder

2026-07-21 18:22:39 +07:00

18 KiB

Raw Blame History

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:

[ 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:

          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:

[ 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:

  +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:

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

+─────────────────────────────────────────────────────────────────────────────────────────────+
|  [● 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.

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

18 KiB Raw Blame History