Camilla DSP 使用介紹

[人生不可重來]

CamillaDSP 是一個基於 command line 電腦 DSP 程式，優點是穩定、容易修改、靈活與方便使用。這篇文章主要講我把這個軟體佈署到電腦裡的過程。如果你有額外需要的情形，歡迎到 CamillaDSP 的 github 找相關訊息。相信你會有不少收穫。

CamillaDSP 作為一個電腦 DSP，可以對音訊處理。包括數位分音(Digital Crossover)、放置等化器(Equilizer)、時間延遲、FIR、IIR、音量增益(gain)、最大音量限制、響度補償曲線等等功能。各項設定都被寫入一個 YAML 檔案中，編輯完後可以很快速的切換各項設定。

恩不過，基於 command line 就表示初期設置不是那麼親民與容易，這也是本文出現的原因。在初期設置
結束以後就可以完整的使用功能了。


畢竟是基於 command line 的東西，所以會需要有一些知識：
1. 如何在 command line 裡面執行檔案
2. 相對路徑與絕對路徑
3. 如何編輯一份 yaml 檔案

[緩慢更新中]

目錄
1. 需要的程式
2. 安裝流程
3. 第一個 YAML 設定檔
4. 從 CamillaGUI 確認設定值是否有問題
5. 從 REW 導入各種 EQ

[人生不可重來]

[Section 1 - MacOS] 需要的程式
* 主程式
* 網頁設定界面 （非必需，建議安裝）
* PEQ 設定網頁 （非必需）
* REW
* BlackHole 2ch

[Section 2 - MacOS] 安裝流程
可以參考DIYaudio 教學

## 安裝主程式
1. 從 github 上面下載最新版本並解壓縮。需要考慮屬於 MacOS, Linux 或是 Windows，以及自己的電腦是 X86_64 / ARM 之類的問題。


2. 安裝相依的 python 套件包 pycamilladsp pycamilladsp-plot

## 安裝 GUI
1. 從 github 上面下載最新版本並解壓縮。通常版本號會跟主程式的版本號一致。

2. 安裝相依的 python 套件包 websocket_client aiohttp jsonschema


---------------------------------------
終端機命令

代碼: 選擇全部

#!/usr/bin/env sh
## Main program installation
# step1 Download main program from github releases and unzip it.
wget https://github.com/HEnquist/camilladsp/releases/download/v2.0.0/camilladsp-macos-aarch64.tar.gz && tar -xvf camilladsp-macos-amd64.tar.gz

# step2 Dependencies installation
pip3 install git+https://github.com/HEnquist/pycamilladsp.git
pip3 install git+https://github.com/HEnquist/pycamilladsp-plot.git

## GUI installation
# step1 Download GUI from github releases and unzip it
wget https://github.com/HEnquist/camillagui-backend/releases/download/v2.0.0/camillagui.zip && unzip camillagui.zip

# step2 Dependencies installation
pip3 install websocket_client aiohttp jsonschema


這時候檔案安裝的位置非常重要，需要注意 camillaDSP 跟 camillagui 這兩個解壓縮後放在哪邊。
這樣一來就可以準備啟動了。

[tim.chnan]

CamillaDSP 是一個基於 command line 電腦 DSP 程式，優點是穩定、容易修改、靈活與方便使用。這篇文章主要講我把這個軟體佈署到電腦裡的過程。如果你有額外需要的情形，歡迎到 CamillaDSP 的 github 找相關訊息。相信你會有不少收穫。
https://github.com/HEnquist/camilladsp

CamillaDSP 作為一個電腦 DSP，可以對音訊處理。包括數位分音(Digital Crossover)、放置等化器(Equilizer)、時間延遲、FIR、IIR、音量增益(gain)、最大音量限制、響度補償曲線等等功能。各項設定都被寫入一個 YAML 檔案中，編輯完後可以很快速的切換各項設定。

[緩慢更新中]

讚喔，我覺得 Software-based DSP/X-over 是一個適合長期研究精進的 project
特別是校正完一組 config 之後的長時間聆聽驗證

電腦直接透過多路數位輸出，我覺得幾種傳輸界面都很有意思，如果 PC/Mac/R-pi 可直接透過 CamillaDSP 控制的話：
[ADAT] ----------------------------------------------------
ebay 上滿滿的舊世代多音路錄音介面 (沒有 USB/Madi, 只有 ADAT, 無法直接透過介面做 X-over), 只要 Camilla DSP + R-Pi 能夠解放 DSP 的話
滿有搞頭的，像是 Lynx Aurora, RME Fireface 800, Nuendo (RME代工) 8-I/O, Apogee Rosetta, 都可以用很優異的價錢取得
( R-pi 如果走多路數位輸出到舊世代錄音介面，通常是透過 ADAT光纖, 這時候需要像是 MiniDSP MCHStreamer 這種裝置作為媒介)

[Multi-channel USB] ----------------------------------------------------
例如說像是高價錄音介面 (RME UFX, Motu Ultralite mk3~5), MiniDSP, 或是 DIYHK 的 multi-channel XMOS USB -> DAC kits
或是 TI or Infineon 都有多音路DSP 解決方案 (like TLV320AIC34EVM)

[R-pi Multi-channel HDMI] ----------------------------------------------------
接下來 CamillaDSP 應該使用的人會變多，因為 R-pi 5 的 HDMI 可以同時輸出 Multi-channel PCM
所以 "R-pi 5 + Camilla DSP => 多聲道環擴" 會成為簡易方便的數位主動分音喇叭設定

不過我之前短暫/無腦使用 Camilla DSP 的時候，沒找到怎麼 real-time 整合 audio inputs
(linux 的音訊輸出協定, 實在讓我霧煞煞: wasabe.....etc.)
1. 如果只想把 Pi/PC/Mac 當作中繼的訊號處理器，訊號源是 CD/TV/PS5/Xbox 之類，或甚至多訊號切換/Mix
2. 或是想要 real-time 接一個麥克風，做及時 DRC or 響度校正

[BBOsip]

this phrase has had just by the way

[人生不可重來]

[Section 3] 第一個 YAML 檔案

## 什麼是 YAML 檔案
YAML 檔是一種文字檔案，非常重視縮排的特性相當類似 python 的編輯邏輯，這個規則讓編輯跟閱讀變得相當容易，但對於新手來說很容易編寫錯誤讓程式看不懂。如果你編輯完以後發現沒反應，那大概是縮排出問題了。為了減少縮排問題帶來的影響，建議你使用比較專門的編輯器，避免使用 TextEdit、Word 或是 Pages 之類的程式編輯 YAML 檔案。使用 VS Code、Sublime Text 或是 vim、 Emacs 之類的程式會讓編寫過程比較順利一些。

範例：這兩種 YAML 檔案代表的意義並不一樣

代碼: 選擇全部

devices:
  samplerate: 44100
  chunksize: 1024
  capture:
    type: File
    filename: "dummy"
    channels: 2
    format: S16LE
  playback:
    type: File
    filename: "dummy"
    channels: 2
    format: S16LE


代碼: 選擇全部

devices:
  samplerate: 44100
  chunksize: 1024
  capture:
  type: File
  filename: "dummy"
  channels: 2
  format: S16LE
  playback:
    type: File
    filename: "dummy"
    channels: 2
    format: S16LE


另外，也需要注意的是看到的 YAML 檔案內容會隨著 CamillaDSP 的版本會有些許不一樣。這篇文章依據 CamillaDSP 2.0.3 撰寫，也許 CamillaDSP 更新以後會有不一樣的寫法。如果發現問題的話，請以 GitHub 裡面的說明為準。



## CamillaDSP 需要什麼樣的訊息

根據 GitHub 的描述，CamillaDSP 會需要

* [Devices] 音樂訊號輸入與輸出
* [Resampling] 重新取樣訊號
* [Mixers] 訊號混合，有沒有需要增減數位通道
* [Filters] 訊號過濾，做各種處理。
** [Gain] 訊號增益，讓訊號變大變小
** [Volume] 整體音量控制，音控如何動作
** [Loudness] 整體響度補償，設定不同音量控制的時候如何補償高低頻響應
** [Delay] 訊號時間延遲，讓訊號晚點出現
** [FIR] 讓訊號根據載入檔案補償 FIR 曲線
** [IIR] 一般所說的 EQ，寫入各種 IIR 濾波器
** [Dither] 幫訊號增加雜訊
** [Limiter] 訊號限制器，如何處理削波 (Clipping) 的訊號
** [Difference equation] 用數學函數調整訊號響應
* [Processors] 多組數位訊號處理，目前只有壓縮器一項可以用
** [Compressor] 訊號壓縮器，可以壓縮動態範圍
* [Pipeline] 資料處理流程，照順序處理定義過的處理單元

## 一個簡單的 YAML 檔案
我用來測試 CamillaDSP 的檔案是實作一個單聲道的數位分音。將我的兩聲道 DAC 轉換為一邊是推高音，一邊推低音。

### 輸入與輸出
第一項需要的是設定輸入與輸出，這個在 devices 欄位裡面定義。要讓 CamillaDSP 處理你的音訊，你需要先將電腦的聲音輸出到安裝好的 BlackHole 裡面，換句話說就是把聲音輸出給 BlackHole，然後 CamillaDSP 從 BlackHole 截取訊號處理完丟給你的 DAC。


你會需要打開 MacOS 裡面的 "Audio MIDI Setup"，裡面會有比較多的相關資訊。在這裡你可以找到 CamillaDSP 需要的內容。

你可以在裡面找到「設備名稱」、「格式」、「Sample Rate」、「channel 數量」等等的訊息。（註1）
一個好的設定會長的下面這樣：

代碼: 選擇全部

devices:
  adjust_period: 10
  capture:
    change_format: false
    channels: 2
    device: BlackHole 16ch
    format: FLOAT32LE
    type: CoreAudio
  capture_samplerate: 48000
  chunksize: 4096
  enable_rate_adjust: true
  enable_resampling: true
  playback:
    change_format: false
    channels: 2
    device: 'USB Audio DAC   '
    exclusive: false
    format: S16LE
    type: CoreAudio
  queuelimit: 4
  rate_measure_interval: 1
  resampler_type: BalancedAsync
  samplerate: 48000
  silence_threshold: -100
  silence_timeout: 5
  stop_on_rate_change: false
  target_level: 0


在這份範例裡面，CamillaDSP 從 BlackHole 16ch 截取音樂，這個 BlackHole 16ch 使用了 FLOAT32LE 的音樂格式，BlackHole 16ch 擁有 2 個 channel 並且使用了 48000Hz 的 Sample Rate (capture_samplerate: 48000)。然後決定我的輸出是 "USB Audio DAC " （註1），擁有兩個 channel， 48000 Hz 的 Sample Rate (samplerate: 48000)並且使用 S16LE 格式。此外 CamillaDSP 並不會獨佔這個 DAC (exclusive: false)


註1 ：如果你照著打名字還是發現 CamillaDSP 找不到 DAC，那恭喜你遇到噁心的問題了，這表示你的 DAC 製造商寫了空格在你的 DAC 名字內，所以你必須將空格也擺進 DAC 名字內。這時候 Audio MIDI Setup 程式雖然顯示了正確的名稱，但人眼無法讀取到底有幾個空格在裡面。因此你必須使用 terminal 並執行指令

代碼: 選擇全部

 system_profiler SPAudioDataType

然後複製正確的字串。


### Filter
CamillaDSP 最重要的設定就是要對音訊做處理，每項處理都是一個 Filter 模組。每個模組都有自己的名字、種類 (type) 跟參數 (parameters)。而且你可以從範例程式碼裡面發現，定義 Filter 模組的時候並沒有定義他被用在什麼地方。這裡僅僅是定義功能，作用的範圍記載於 pipeline 區域。
這裡的定義是不分順序的，每一個 Filter 都是獨立的模組，不會互相影響。

代碼: 選擇全部

filters:
  my_example_delay:
    type: Delay
    parameters:
      delay: 0.019
      unit: ms
      subsample: false
  low_pass_filter:
    parameters:
      freq: 2200.0
      order: 4
      type: ButterworthLowpass
    type: BiquadCombo
  high_pass_filter:
    parameters:
      freq: 2200.0
      order: 4
      type: ButterworthHighpass
    type: BiquadCombo


這裡你可以看到我寫了三個 filter，延遲、高通與低通。這裡名字可以亂取，但不能重複。

### Mixer 混音器
混音器 Mixer 定義了輸入與輸出該怎麼對應的問題。想像你的音樂是一個兩聲道音樂，而 DAC 卻是八聲道的情況，這種情況顯然就不能夠一對一對應了。混音器 Mixer 就會是你需要定義的東西。

代碼: 選擇全部

mixers:
  1x2:
    channels:
      in: 2
      out: 2
    mapping:
    - dest: 0
      mute: false
      sources:
      - channel: 0
        gain: 0
        inverted: false
        mute: false
    - dest: 1
      mute: false
      sources:
      - channel: 0
        gain: 0
        inverted: false
        mute: false


在這裡我的例子是兩聲道音樂僅僅使用了左聲道，然而這個左聲道音樂都被輸出到 DAC 的兩個聲道裡。這樣我可以對輸出的音樂做後續處理。



### Pipeline 資料流
Pipeline 定義了資料處理的順序，在這裡是使用列表來呈現，先定義好的東西會先被執行。而你需要知道的是，一開始的時候這個音樂是兩聲道音樂，經過了你定義的功能以後，這個音樂變成什麼了？

代碼: 選擇全部

pipeline:
  - type: Mixer
    description: 'let channel 0 occupies output channel 0 and 1'
    name: 1x2
  - type: Filter
    channel: 0
    description: 'output left channel as a tweeter'
    names:
      - high_pass_filter
      - my_example_delay
  - type: Filter
    description: 'output right channel as a woofer'
    channel: 1
      - low_pass_filter


在這個範例裡面，一開始的兩聲道音樂先經過 (1) Mixer: 1x2，在這裡他把兩聲道音樂變成單聲道音樂，而且 channel0 跟 channel1 的聲音是一樣的。然後經過 (2) Filter，這個 Filter 是作用在 channel0 上，讓 channel0 通過高通和延遲模組。最後是 (3) Filter，這個 Filter 作用在 channel1 上，讓 channel1 通過低通模組。


*********************** 錯誤範例 ***********************

代碼: 選擇全部

pipeline:
  - type: Filter
    channel: 0
    description: 'output left channel as a tweeter'
    names:
      - high_pass_filter
      - my_example_delay
  - type: Filter
    description: 'output right channel as a woofer'
    channel: 1
      - low_pass_filter
  - type: Mixer
    description: 'let channel 0 occupies output channel 0 and 1'
    name: 1x2


如果這份檔案的順序調換了，那麼解讀的方式會變得不一樣。在這個情況下，音樂的兩聲道會在 (1) 左聲道 channel0 通過一個高通和延遲模組，然後在 (2) 右聲道 channel1 通過一個低通模組。最後在 (3) Mixer 的部分把右聲道丟掉，讓左聲道的音樂被放進 DAC 的 channel 0 和 channel 1 中

*********************** 錯誤範例 ***********************

### 完整程式碼
這邊是完整的程式碼，你可以從這裡複製上述提到的所有程式碼，好讓你的 CamillaDSP 開始動作。不過要記得，你還是需要修改輸入與輸出才能夠讓 CamillaDSP 開始動作

代碼: 選擇全部

devices:
  adjust_period: 10
  capture:
    change_format: false
    channels: 2
    device: BlackHole 16ch
    format: FLOAT32LE
    type: CoreAudio
  capture_samplerate: 48000
  chunksize: 4096
  enable_rate_adjust: true
  enable_resampling: true
  playback:
    change_format: false
    channels: 2
    device: 'USB Audio DAC   '
    exclusive: false
    format: S16LE
    type: CoreAudio
  queuelimit: 4
  rate_measure_interval: 1
  resampler_type: BalancedAsync
  samplerate: 48000
  silence_threshold: -100
  silence_timeout: 5
  stop_on_rate_change: false
  target_level: 0
filters:
  my_example_delay:
    type: Delay
    parameters:
      delay: 0.019
      unit: ms
      subsample: false
  low_pass_filter:
    parameters:
      freq: 2200.0
      order: 4
      type: ButterworthLowpass
    type: BiquadCombo
  high_pass_filter:
    parameters:
      freq: 2200.0
      order: 4
      type: ButterworthHighpass
    type: BiquadCombo
mixers:
  1x2:
    channels:
      in: 2
      out: 2
    mapping:
    - dest: 0
      mute: false
      sources:
      - channel: 0
        gain: 0
        inverted: false
        mute: false
    - dest: 1
      mute: false
      sources:
      - channel: 0
        gain: 0
        inverted: false
        mute: false
pipeline:
  - type: Mixer
    description: 'let channel 0 occupies output channel 0 and 1'
    name: 1x2
  - type: Filter
    channel: 0
    description: 'output left channel as a tweeter'
    names:
      - high_pass_filter
      - my_example_delay
  - type: Filter
    description: 'output right channel as a woofer'
    channel: 1
      - low_pass_filter