14 KiB
14 KiB
Technical Specification: Advanced Editing Toolset & Volume Automation Envelope on Sub-Tab
This document defines the interactive layout design and signal processing algorithms for the advanced localized editing toolset contained within the isolated temporary document workspace (Sub-tab).
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 to0\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 multiplierG:
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 attenuation adjustments:
Linear Fade-In Exponential Fade-Out
+───────────────────────────+ +───────────────────────────+
| /███████████████| |███████████\ |
| / ███████████████| |███████████ \ |
| / ███████████████| |███████████ \___ |
| / ███████████████| |███████████ \______|
+───────────────────────────+ +───────────────────────────+
|<──────── Fade-In ────────>| |<─────── Fade-Out ────────>|
- Fade-In: Multiplies an ascending amplitude ramp from
0.0to1.0at the starting index profile of the selection region. Users can toggle 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.0down to0.0at 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% (Half Speed) - 200% (Double Speed)
- Interaction Mapping: Users drag the percentage slider node or hold down the
Altkey and drag the rightmost boundary edge of the clip along the horizontal axis to change this scale metric. - Sync Formula: Let
Dmap to the unscaled native duration value, andD'map to the target modified duration footprint. The resulting structural playback speed ratio percentage (S) is given by:
S = \frac{D}{D'} \times 100\%
- UI Representation: A bright yellow text metadata indicator (e.g.,
Speed: 85.3%) is rendered at the top-left section of the audio clip bounding boundary.
5. Ultra-Zoom & Zero-Crossing Alignment
To facilitate precision structural slicing at sample-level resolutions, the sub-tab canvas allows microscopic viewport expansion:
MICRO VIEWPORT ZOOM (ULTRA ZOOM-IN)
+─────────────────────────────────────────────────────────────────+
| Waveform renders discrete contiguous sample nodes explicitly |
| ○ (Sample i) |
| / \ |
| ─────────────────/───\─────────────────────────────► 0V Axis |
| \ ○ (Sample i+2) |
| \ / |
| \_○ (Sample i+1 - Zero-Crossing Point)|
+─────────────────────────────────────────────────────────────────+
- Upper Viewport Scaling Limit: Allows zooming in up to an extreme lower threshold of
2000\text{ pixels/second}. At this zoom metric, layout compilation transitions away from downsampled peak profiles (Peak Waveform) to render actual discrete sample nodes interconnected by fine lines. - Zero-Line Snapping Logic: When establishing selection boundaries, the tracking loop automatically snaps the horizontal selection cursor coordinate to the nearest available sample address exhibiting an algebraic phase inversion (sign change):
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
A prominent master transport toolbar occupies the bottom row layout of the sub-tab layout to manage audio playback monitoring:
+───────────────────────────────────────────────────────────────────────────+
| [Back to Start] [Play] [Pause] [Stop] | Loop Sequence: [X] |
+───────────────────────────────────────────────────────────────────────────+
- Back to Start: Instantly updates the regional playhead time parameter back to the absolute starting point (
t = 0.0\text{ s}). - Play / Pause / Stop: Drives regional audio engine playback loops restricted entirely to the data buffers allocated inside the current sub-tab workspace.
- Loop Toggle: Toggles continuous cycle loops over the highlighted section or the whole clip.
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 Pen Tool icon in the control panel modifies the pointer device presentation into a drawing crosshair or 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{V_{\text{dB}}(t)}{20}}
x_{\text{automation}}[n] = x[n] \cdot G_{\text{linear}}\left( \frac{n}{\text{Sample Rate}} \right)
9. Python Porting Manual (Docker Server Platform)
When translating these graphical volume automation envelope features to a desktop PyQt6 interface or an asynchronous Celery Docker worker pipeline, the standard scientific function numpy.interp handles array vector scaling processing loops:
import numpy as np
def apply_volume_automation_envelope(y: np.ndarray, sr: int, nodes: list) -> np.ndarray:
"""
Applies a user-drawn volume automation envelope onto an acoustic signal NumPy array.
nodes: A list of point dictionaries, e.g., [{"time": 0.0, "db": 0.0}, {"time": 2.5, "db": -12.0}, ...]
"""
if not nodes:
return y
# Sort envelope nodes chronologically by time axis
nodes = sorted(nodes, key=lambda x: x["time"])
# 1. Map node variables into distinct coordinates arrays
node_times = np.array([node["time"] for node in nodes])
node_dbs = np.array([node["db"] for node in nodes])
# Hard-clamp boundary constraints matching the operational floor [-30.0dB, +3.0dB]
node_dbs = np.clip(node_dbs, -30.0, 3.0)
# 2. Evaluate absolute timeline timestamps for every index position inside the signal array
total_samples = len(y)
sample_times = np.arange(total_samples) / sr
# 3. Linearly interpolate localized decibel thresholds across every single sample step
interpolated_dbs = np.interp(sample_times, node_times, node_dbs, left=node_dbs[0], right=node_dbs[-1])
# 4. Map logarithmic values into standard linear gain scale arrays
linear_gains = 10.0 ** (interpolated_dbs / 20.0)
# 5. Multiply the raw amplitude vector array by the linear gain modifier mask
return y * linear_gains