desktop-team-doc 0.1.0

package/content/docs/knowledge/component-library/ControlComponent/interaction/velocity-damping-systems.md

@@ -0,0 +1,741 @@
+# 速度感應與阻尼系統
+
+本文檔詳細說明音訊控制項中的速度感應 (Velocity Sensitivity) 和阻尼效果 (Damping) 系統，這兩種機制是專業音訊軟體的核心特性。
+
+---
+
+## 1. Damping vs Velocity 的本質區別
+
+### 概念區分
+
+這兩種功能滿足使用者在不同情境下的需求：
+
+| 特性 | 阻尼效果 (Damping) | 速度感應 (Velocity) |
+|------|-------------------|-------------------|
+| **觸發方式** | 修飾鍵 (Shift/Ctrl) | 滑鼠移動速度 |
+| **效果** | 固定降低靈敏度 | 動態調整靈敏度 |
+| **使用情境** | 刻意的精細微調 | 快速粗調 + 慢速精調 |
+| **範例** | 調整 EQ 增益、濾波器共振 | 掃過合成器頻率範圍 |
+
+### JUCE 論壇的關鍵洞察
+
+> "在速度感應模式下，拖動滑桿的精確度取決於你滑鼠移動的速度...但在精細模式下，滑桿只是單純地變得更慢。"
+> — JUCE 開發者論壇
+
+### 正交設計原則
+
+這兩種功能是**正交的**，可以獨立使用或同時作用：
+
+```typescript
+// 最終變化量公式
+finalChange = baseChange * dampingMultiplier * velocityMultiplier
+
+// 當使用者按住 Shift 並快速移動時：
+// - damping 先降低基礎變化量
+// - velocity 再根據速度放大結果
+// 結果：快速移動時有適度放大，但基底已被阻尼降低
+```
+
+---
+
+## 2. 阻尼效果 (Damping) 系統
+
+### 修飾鍵配置策略
+
+不同平台有不同的慣例，應該允許配置：
+
+```typescript
+/**
+ * 阻尼配置
+ */
+interface DampingConfig {
+  enabled?: boolean;
+  key?: 'shift' | 'ctrl' | 'alt' | 'meta';
+  factor?: number;  // 0.1 = 1/10 靈敏度
+  dynamic?: {
+    adaptToRange?: boolean;   // 根據參數範圍自動調整
+    adaptToPrecision?: boolean; // 根據當前精確度調整
+  };
+}
+
+/**
+ * 預設配置 (可覆蓋)
+ */
+const DEFAULT_DAMPING: DampingConfig = {
+  enabled: true,
+  key: 'shift',  // 業界最常見
+  factor: 0.1,   // 1/10 靈敏度
+};
+```
+
+### BIAS ONE 現有實作
+
+```typescript
+// BIAS ONE 現有的精確模式檢測 (來自 common-mechanisms.md)
+const usePreciseMode = () => {
+  const agent = useAgent();
+
+  const isPreciseMode = useCallback((e: MouseEvent | WheelEvent) => {
+    return (agent.isMac && e.metaKey) || (agent.isWin && e.ctrlKey);
+  }, [agent]);
+
+  return isPreciseMode;
+};
+
+// 在 Slider 中的應用
+const PRECISE_DRAG_SENSITIVITY = 0.2;  // = factor 0.2
+const DRAG_SENSITIVITY = 1;
+
+const sensitivity = isPreciseMode(event)
+  ? PRECISE_DRAG_SENSITIVITY
+  : DRAG_SENSITIVITY;
+```
+
+### 建議改進：可配置的阻尼系統
+
+```typescript
+/**
+ * 阻尼處理器
+ */
+class DampingProcessor {
+  private config: DampingConfig;
+
+  constructor(config: DampingConfig = DEFAULT_DAMPING) {
+    this.config = config;
+  }
+
+  /**
+   * 檢查是否啟用阻尼
+   */
+  isDamped(event: PointerEvent | MouseEvent | WheelEvent): boolean {
+    if (!this.config.enabled || !this.config.key) {
+      return false;
+    }
+
+    const keyMap: Record<string, keyof PointerEvent> = {
+      shift: 'shiftKey',
+      ctrl: 'ctrlKey',
+      alt: 'altKey',
+      meta: 'metaKey',
+    };
+
+    return Boolean(event[keyMap[this.config.key]]);
+  }
+
+  /**
+   * 獲取阻尼乘數
+   */
+  getMultiplier(event: PointerEvent | MouseEvent | WheelEvent): number {
+    return this.isDamped(event) ? (this.config.factor ?? 0.1) : 1.0;
+  }
+
+  /**
+   * 應用阻尼到數值變化
+   */
+  apply(delta: number, event: PointerEvent | MouseEvent | WheelEvent): number {
+    return delta * this.getMultiplier(event);
+  }
+}
+```
+
+---
+
+## 3. 速度感應 (Velocity) 系統
+
+### VelocityTracker 完整實作
+
+```typescript
+/**
+ * 速度追蹤器配置
+ */
+interface VelocityTrackerConfig {
+  maxSamples?: number;      // 最大樣本數，預設 10
+  timeWindow?: number;      // 時間窗口 (ms)，預設 100
+  smoothingFactor?: number; // 平滑因子，預設 0.3
+}
+
+/**
+ * 速度樣本
+ */
+interface VelocitySample {
+  position: Point;
+  timestamp: number;
+}
+
+/**
+ * 高精度速度追蹤器
+ */
+class VelocityTracker {
+  private samples: VelocitySample[] = [];
+  private config: Required<VelocityTrackerConfig>;
+
+  constructor(config: VelocityTrackerConfig = {}) {
+    this.config = {
+      maxSamples: 10,
+      timeWindow: 100,
+      smoothingFactor: 0.3,
+      ...config,
+    };
+  }
+
+  /**
+   * 添加位置樣本
+   */
+  addSample(position: Point, timestamp: number = performance.now()): void {
+    this.samples.push({ position, timestamp });
+
+    // 清理過期樣本
+    this.cleanupSamples(timestamp);
+
+    // 限制樣本數量
+    while (this.samples.length > this.config.maxSamples) {
+      this.samples.shift();
+    }
+  }
+
+  /**
+   * 重置追蹤器
+   */
+  reset(): void {
+    this.samples = [];
+  }
+
+  /**
+   * 計算瞬時速度 (最近兩點)
+   * 單位：像素/毫秒
+   */
+  getInstantVelocity(): number {
+    if (this.samples.length < 2) return 0;
+
+    const latest = this.samples[this.samples.length - 1];
+    const previous = this.samples[this.samples.length - 2];
+
+    return this.calculateVelocityBetween(previous, latest);
+  }
+
+  /**
+   * 計算平均速度 (時間窗口內)
+   */
+  getAverageVelocity(): number {
+    if (this.samples.length < 2) return 0;
+
+    let totalDistance = 0;
+
+    for (let i = 1; i < this.samples.length; i++) {
+      const prev = this.samples[i - 1];
+      const curr = this.samples[i];
+      totalDistance += this.calculateDistance(prev.position, curr.position);
+    }
+
+    const timeSpan =
+      this.samples[this.samples.length - 1].timestamp -
+      this.samples[0].timestamp;
+
+    return timeSpan > 0 ? totalDistance / timeSpan : 0;
+  }
+
+  /**
+   * 計算平滑速度 (指數移動平均)
+   * 最推薦使用，能有效過濾雜訊
+   */
+  getSmoothedVelocity(): number {
+    if (this.samples.length < 2) return 0;
+
+    let smoothedVelocity = 0;
+    const alpha = this.config.smoothingFactor;
+
+    for (let i = 1; i < this.samples.length; i++) {
+      const velocity = this.calculateVelocityBetween(
+        this.samples[i - 1],
+        this.samples[i]
+      );
+
+      // 指數移動平均: EMA = α * current + (1-α) * previous
+      smoothedVelocity = alpha * velocity + (1 - alpha) * smoothedVelocity;
+    }
+
+    return smoothedVelocity;
+  }
+
+  /**
+   * 計算加速度 (速度變化率)
+   */
+  getAcceleration(): number {
+    if (this.samples.length < 3) return 0;
+
+    const velocities: number[] = [];
+    for (let i = 1; i < this.samples.length; i++) {
+      velocities.push(
+        this.calculateVelocityBetween(this.samples[i - 1], this.samples[i])
+      );
+    }
+
+    if (velocities.length < 2) return 0;
+
+    const latestVelocity = velocities[velocities.length - 1];
+    const previousVelocity = velocities[velocities.length - 2];
+    const timeDelta =
+      this.samples[this.samples.length - 1].timestamp -
+      this.samples[this.samples.length - 2].timestamp;
+
+    return timeDelta > 0 ? (latestVelocity - previousVelocity) / timeDelta : 0;
+  }
+
+  /**
+   * 獲取方向性速度 (用於判斷移動方向)
+   */
+  getDirectionalVelocity(): Point {
+    if (this.samples.length < 2) return { x: 0, y: 0 };
+
+    const latest = this.samples[this.samples.length - 1];
+    const previous = this.samples[this.samples.length - 2];
+    const timeDelta = latest.timestamp - previous.timestamp;
+
+    if (timeDelta <= 0) return { x: 0, y: 0 };
+
+    return {
+      x: (latest.position.x - previous.position.x) / timeDelta,
+      y: (latest.position.y - previous.position.y) / timeDelta,
+    };
+  }
+
+  private calculateVelocityBetween(
+    sample1: VelocitySample,
+    sample2: VelocitySample
+  ): number {
+    const distance = this.calculateDistance(sample1.position, sample2.position);
+    const timeDelta = sample2.timestamp - sample1.timestamp;
+
+    return timeDelta > 0 ? distance / timeDelta : 0;
+  }
+
+  private calculateDistance(p1: Point, p2: Point): number {
+    const dx = p2.x - p1.x;
+    const dy = p2.y - p1.y;
+    return Math.sqrt(dx * dx + dy * dy);
+  }
+
+  private cleanupSamples(currentTime: number): void {
+    const cutoffTime = currentTime - this.config.timeWindow;
+    this.samples = this.samples.filter(
+      (sample) => sample.timestamp >= cutoffTime
+    );
+  }
+}
+```
+
+---
+
+## 4. VelocityResponseCalculator 響應曲線
+
+### 多種響應曲線實作
+
+```typescript
+/**
+ * 速度配置
+ */
+interface VelocityConfig {
+  enabled?: boolean;
+  sensitivity?: number;     // 速度影響強度
+  threshold?: number;       // 啟動閾值
+  maxMultiplier?: number;   // 最大乘數上限
+  curve?: 'linear' | 'exponential' | 'logarithmic' | 'sigmoid' | 'custom';
+  exponent?: number;        // exponential 曲線的指數
+  steepness?: number;       // sigmoid 曲線的陡度
+  controlPoints?: ControlPoint[];  // custom 曲線的控制點
+}
+
+/**
+ * 控制點 (用於自訂曲線)
+ */
+interface ControlPoint {
+  x: number;  // 0-1 範圍的速度比
+  y: number;  // 對應的乘數
+}
+
+/**
+ * 速度響應曲線計算器
+ */
+class VelocityResponseCalculator {
+  /**
+   * 計算速度乘數
+   * @param velocity 當前速度 (像素/毫秒)
+   * @param config 速度配置
+   * @returns 乘數 (1.0 = 無影響)
+   */
+  static calculateMultiplier(velocity: number, config: VelocityConfig): number {
+    if (!config.enabled) {
+      return 1.0;
+    }
+
+    const threshold = config.threshold ?? 0.5;
+
+    // 低於閾值時不啟用
+    if (velocity < threshold) {
+      return 1.0;
+    }
+
+    // 正規化速度
+    const normalizedVelocity = velocity - threshold;
+    const maxVelocity = 10.0; // 預設最大速度參考值
+    const velocityRatio = Math.min(1, normalizedVelocity / maxVelocity);
+
+    let multiplier: number;
+
+    switch (config.curve) {
+      case 'linear':
+        multiplier = this.calculateLinearResponse(velocityRatio, config);
+        break;
+
+      case 'exponential':
+        multiplier = this.calculateExponentialResponse(velocityRatio, config);
+        break;
+
+      case 'logarithmic':
+        multiplier = this.calculateLogarithmicResponse(velocityRatio, config);
+        break;
+
+      case 'sigmoid':
+        multiplier = this.calculateSigmoidResponse(velocityRatio, config);
+        break;
+
+      case 'custom':
+        multiplier = this.calculateCustomResponse(velocityRatio, config);
+        break;
+
+      default:
+        multiplier = 1.0;
+    }
+
+    // 限制在合理範圍內
+    const minMultiplier = 0.1;
+    const maxMultiplier = config.maxMultiplier ?? 10.0;
+
+    return Math.max(minMultiplier, Math.min(maxMultiplier, multiplier));
+  }
+
+  /**
+   * 線性響應曲線
+   * 速度與乘數成正比
+   */
+  private static calculateLinearResponse(
+    ratio: number,
+    config: VelocityConfig
+  ): number {
+    const sensitivity = config.sensitivity ?? 1;
+    return 1 + ratio * sensitivity;
+  }
+
+  /**
+   * 指數響應曲線
+   * 高速時乘數快速增加
+   */
+  private static calculateExponentialResponse(
+    ratio: number,
+    config: VelocityConfig
+  ): number {
+    const exponent = config.exponent ?? 2;
+    const sensitivity = config.sensitivity ?? 1;
+    return 1 + Math.pow(ratio, exponent) * sensitivity;
+  }
+
+  /**
+   * 對數響應曲線
+   * 低速時變化明顯，高速時趨緩
+   */
+  private static calculateLogarithmicResponse(
+    ratio: number,
+    config: VelocityConfig
+  ): number {
+    const sensitivity = config.sensitivity ?? 1;
+    // log(1 + x*(e-1)) 確保 x=0 時 y=0，x=1 時 y=1
+    return 1 + Math.log(1 + ratio * (Math.E - 1)) * sensitivity;
+  }
+
+  /**
+   * S 型曲線 (Sigmoid)
+   * 中速區間變化最明顯
+   */
+  private static calculateSigmoidResponse(
+    ratio: number,
+    config: VelocityConfig
+  ): number {
+    const steepness = config.steepness ?? 5;
+    const sensitivity = config.sensitivity ?? 1;
+
+    // Sigmoid: 1 / (1 + e^(-k*(x-0.5)))
+    const sigmoid = 1 / (1 + Math.exp(-steepness * (ratio - 0.5)));
+    return 1 + sigmoid * sensitivity;
+  }
+
+  /**
+   * 自訂曲線 (透過控制點插值)
+   */
+  private static calculateCustomResponse(
+    ratio: number,
+    config: VelocityConfig
+  ): number {
+    const controlPoints = config.controlPoints ?? [
+      { x: 0, y: 1 },
+      { x: 1, y: 1 + (config.sensitivity ?? 1) },
+    ];
+
+    return this.interpolateControlPoints(ratio, controlPoints);
+  }
+
+  /**
+   * 控制點線性插值
+   */
+  private static interpolateControlPoints(
+    x: number,
+    points: ControlPoint[]
+  ): number {
+    if (points.length === 0) return 1;
+    if (points.length === 1) return points[0].y;
+
+    // 排序控制點
+    const sortedPoints = [...points].sort((a, b) => a.x - b.x);
+
+    // 找到 x 所在的區間
+    for (let i = 0; i < sortedPoints.length - 1; i++) {
+      const p1 = sortedPoints[i];
+      const p2 = sortedPoints[i + 1];
+
+      if (x >= p1.x && x <= p2.x) {
+        // 線性插值
+        const t = (x - p1.x) / (p2.x - p1.x);
+        return p1.y + t * (p2.y - p1.y);
+      }
+    }
+
+    // 超出範圍，返回邊界值
+    if (x < sortedPoints[0].x) {
+      return sortedPoints[0].y;
+    }
+    return sortedPoints[sortedPoints.length - 1].y;
+  }
+}
+```
+
+### 響應曲線視覺化參考
+
+```
+乘數
+ 10 |                                    ______ exponential
+    |                               ____/
+  5 |                          ____/
+    |                     ____/  ______ linear
+    |                ____/ ____/
+    |           ____/____/_______ logarithmic
+  1 |__________/____/
+    |_______________________________________
+    0                                     速度
+                     threshold
+```
+
+---
+
+## 5. BIAS ONE 現有實作對照
+
+### 現有常數
+
+```typescript
+// BIAS ONE Slider 常數
+const DRAG_SENSITIVITY = 1;
+const PRECISE_DRAG_SENSITIVITY = 0.2;  // = damping factor 0.2
+
+// BIAS ONE Knob 常數
+const WHEEL_DEFAULT_SENSITIVITY = 5000;
+const WHEEL_SENSITIVITY_DIVISOR = 15000;
+```
+
+### 現有精確模式實作
+
+```typescript
+// BIAS ONE 精確模式 Hook
+const usePreciseMode = () => {
+  const agent = useAgent();
+
+  return useCallback((e: MouseEvent | WheelEvent) => {
+    return (agent.isMac && e.metaKey) || (agent.isWin && e.ctrlKey);
+  }, [agent]);
+};
+```
+
+### 建議整合方案
+
+```typescript
+/**
+ * 整合的速度-阻尼處理器
+ * 統一處理 BIAS ONE 現有邏輯和新功能
+ */
+class UnifiedSensitivityProcessor {
+  private dampingProcessor: DampingProcessor;
+  private velocityTracker: VelocityTracker;
+  private velocityConfig: VelocityConfig;
+
+  constructor(
+    dampingConfig: DampingConfig,
+    velocityConfig: VelocityConfig
+  ) {
+    this.dampingProcessor = new DampingProcessor(dampingConfig);
+    this.velocityTracker = new VelocityTracker();
+    this.velocityConfig = velocityConfig;
+  }
+
+  /**
+   * 處理指標移動
+   */
+  processPointerMove(
+    event: PointerEvent,
+    baseDelta: number
+  ): number {
+    // 更新速度追蹤
+    this.velocityTracker.addSample(
+      { x: event.clientX, y: event.clientY },
+      event.timeStamp
+    );
+
+    let result = baseDelta;
+
+    // 1. 應用阻尼 (修飾鍵)
+    result = this.dampingProcessor.apply(result, event);
+
+    // 2. 應用速度感應
+    if (this.velocityConfig.enabled) {
+      const velocity = this.velocityTracker.getSmoothedVelocity();
+      const velocityMultiplier = VelocityResponseCalculator.calculateMultiplier(
+        velocity,
+        this.velocityConfig
+      );
+      result *= velocityMultiplier;
+    }
+
+    return result;
+  }
+
+  /**
+   * 處理滾輪事件
+   */
+  processWheel(event: WheelEvent, baseDelta: number): number {
+    // 滾輪通常只應用阻尼，不應用速度感應
+    return this.dampingProcessor.apply(baseDelta, event);
+  }
+
+  /**
+   * 重置 (拖曳結束時)
+   */
+  reset(): void {
+    this.velocityTracker.reset();
+  }
+
+  /**
+   * 獲取當前狀態
+   */
+  getState(): {
+    isDamped: boolean;
+    velocity: number;
+    velocityMultiplier: number;
+  } {
+    const velocity = this.velocityTracker.getSmoothedVelocity();
+    const velocityMultiplier = this.velocityConfig.enabled
+      ? VelocityResponseCalculator.calculateMultiplier(
+          velocity,
+          this.velocityConfig
+        )
+      : 1.0;
+
+    return {
+      isDamped: false, // 需要事件才能判斷
+      velocity,
+      velocityMultiplier,
+    };
+  }
+}
+```
+
+---
+
+## 6. 使用指南
+
+### 基礎使用
+
+```typescript
+// 僅阻尼
+const config = {
+  damping: { enabled: true, key: 'shift', factor: 0.1 },
+};
+
+// 僅速度感應
+const config = {
+  velocity: { enabled: true, curve: 'logarithmic', sensitivity: 2 },
+};
+
+// 兩者組合
+const config = {
+  damping: { enabled: true, key: 'shift', factor: 0.1 },
+  velocity: { enabled: true, curve: 'logarithmic', sensitivity: 2 },
+};
+```
+
+### 不同參數類型的建議配置
+
+| 參數類型 | 阻尼因子 | 速度曲線 | 說明 |
+|---------|---------|---------|------|
+| 頻率 (20-20kHz) | 0.05 | logarithmic | 大範圍，需要精細微調 |
+| 增益 (dB) | 0.1 | linear | 適中範圍 |
+| 百分比 (0-100%) | 0.2 | linear | 小範圍 |
+| 時間 (ms) | 0.1 | exponential | 需要快速掃過大範圍 |
+| Pan (-100 to 100) | 0.15 | linear | 需要精確定位中心 |
+
+### 完整使用範例
+
+```typescript
+// 在 useAudioControl 中使用
+function useAudioControl(options: UseAudioControlOptions) {
+  const processor = useRef(
+    new UnifiedSensitivityProcessor(
+      options.damping ?? { enabled: true, key: 'shift', factor: 0.1 },
+      options.velocity ?? { enabled: false }
+    )
+  );
+
+  const handlePointerMove = useCallback((e: React.PointerEvent) => {
+    const rawDelta = calculateRawDelta(e);
+    const processedDelta = processor.current.processPointerMove(
+      e.nativeEvent,
+      rawDelta
+    );
+
+    // 更新數值...
+  }, []);
+
+  // ...
+}
+```
+
+---
+
+## 總結
+
+### 核心公式
+
+```typescript
+// 完整的數值變化計算
+finalChange = baseDelta * sensitivity * dampingMultiplier * velocityMultiplier
+
+// 其中:
+// - baseDelta: 從手勢轉換得到的原始變化量
+// - sensitivity: 基礎靈敏度
+// - dampingMultiplier: 阻尼乘數 (0.1-1.0)
+// - velocityMultiplier: 速度乘數 (1.0-10.0)
+```
+
+### 選擇指南
+
+| 場景 | 建議配置 |
+|------|---------|
+| 一般參數調整 | 僅阻尼 (Shift + 0.1) |
+| 頻率/大範圍參數 | 阻尼 + 速度感應 (對數曲線) |
+| 專業混音環境 | 完整功能 + 可配置修飾鍵 |
+| 入門級應用 | 僅阻尼 (簡單易懂) |