233 lines
14 KiB
Markdown
233 lines
14 KiB
Markdown
# 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:
|
|
|
|
```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 attenuation 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 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% (Half Speed) - 200% (Double Speed)
|
|
|
|
```
|
|
|
|
* **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\%$$
|
|
|
|
|
|
* **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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```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
|
|
|
|
A prominent master transport toolbar occupies the bottom row layout of the sub-tab layout to manage audio playback monitoring:
|
|
|
|
```text
|
|
+───────────────────────────────────────────────────────────────────────────+
|
|
| [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.
|
|
|
|
```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 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:
|
|
|
|
```python
|
|
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
|
|
|
|
``` |