neutone_sdk
v1.4.0: Benchmarking Tools and PyTorch Updates
Neutons SDK是研究人員的工具，使他們能夠包裝自己的音頻模型，並使用我們的Netons插件將其運行。我們提供功能，既可以將模型在插件中加載，又要將它們貢獻到默認的型號列表中，該模型可供運行該插件的任何人使用。我們希望這將使研究人員能夠輕鬆地嘗試使用DAW，但也為創作者提供了一系列有趣的模型。
朱奇（Juce）是構建音頻插件的行業標準。因此，需要了解C ++才能構建非常簡單的音頻插件。但是，AI音頻研究人員很少能在C ++方面擁有豐富的經驗並能夠構建這樣的插件。此外，這是一項嚴肅的時間投資，可以花在開發更好的算法。 Neutons可以使用諸如Pytorch之類的熟悉工具建立模型，並以最少的Python代碼包裝這些模型來構建模型，從而可以由Netoson插件執行。可以在不到一天的時間內完成模型並在DAW中運行，而無需任何C ++代碼或知識。
SDK為您的模型以及即時的樣本率和立體聲速度轉換提供了自動緩衝輸入和輸出的支持。它使一個模型只能以任何採樣率和任何緩衝尺寸無縫地在DAW中使用預定義的樣品執行。此外，在SDK工具中進行基準測試和分析的工具可以很容易地獲得，因此您可以輕鬆調試並測試模型的性能。
您可以使用pip安裝neutone_sdk ：
pip install neutone_sdk
NEUTONS插件可在https://neutone.space上找到。我們目前提供VST3和AU插件，可用於加載使用此SDK創建的模型。請訪問網站以獲取更多信息。
如果您只想在不詳細描述所有事情的詳細說明中包裝模型，我們為您準備了這些示例。
SDK提供了將現有Pytorch模型包裝的功能，該模型可以使它們在VST插件中可執行。在其核心上，插件將以一定的樣本速率作為輸入發送大量音頻樣品，並期望輸出時有相同數量的樣本。 SDK的用戶可以指定其模型最佳性能的樣本率和緩衝區大小。然後，SDK保證該模型的正向通過將在以下（sample_rate，buffer_size）組合中接收音頻。有四個旋鈕可讓插件的用戶在運行時以其他參數為模型。可以通過SDK根據需要啟用或禁用它們。
使用隨附的導出函數，一系列測試會自動運行，以確保模型按預期行事，並準備由插件加載。
基準測試和分析CLI工具可用於進一步調試和測試包裝模型。可以在一系列模擬的公共DAW（sample_rate，buffere_size）組合以及配置內存和CPU使用情況下基於模型的速度和延遲。
我們在示例目錄中提供了幾種模型。我們將瀏覽最簡單的模型之一，即失真模型。
假設我們有以下pytorch模型。參數將在稍後介紹，我們將暫時關注輸入和輸出。假設此模型接收形狀的張量(2, buffer_size)作為一個輸入，其中buffer_size是可以指定的參數。
class ClipperModel ( nn . Module ):
def forward ( self , x : Tensor , min_val : float , max_val : float , gain : float ) -> Tensor :
return torch . clip ( x , min = min_val * gain , max = max_val * gain )要在VST中運行此功能，我們可以寫的最簡單的包裝器是將WoveformTowaveFormbase Baseclass子群亞級。
class ClipperModelWrapper ( WaveformToWaveformBase ):
@ torch . jit . export
def is_input_mono ( self ) -> bool :
return False
@ torch . jit . export
def is_output_mono ( self ) -> bool :
return False
@ torch . jit . export
def get_native_sample_rates ( self ) -> List [ int ]:
return [] # Supports all sample rates
@ torch . jit . export
def get_native_buffer_sizes ( self ) -> List [ int ]:
return [] # Supports all buffer sizes
def do_forward_pass ( self , x : Tensor , params : Dict [ str , Tensor ]) -> Tensor :
# ... Parameter unwrap logic
x = self . model . forward ( x , min_val , max_val , gain )
return x The method that does most of the work is do_forward_pass .在這種情況下，這只是一個簡單的傳遞，但是我們將在以後使用它來處理參數。
默認情況下，VST以stereo-stereo運行，但是對於模型需要單聲道，我們可以使用is_input_mono和is_output_mono通知SDK，並自動將輸入和輸出自動轉換。如果is_input_mono被切換為平均(1, buffer_size)形狀張量作為輸入而不是(2, buffer_size) 。如果已切換is_output_mono ，則do_forward_pass有望返回單聲張量（Shape (1, buffer_size) ），然後在VST輸出時在兩個通道上重複。這是在SDK中完成的，以避免在每次通過期間不必要的內存分配。
get_native_sample_rates和get_native_buffer_sizes可用於指定任何首選的採樣率或緩衝尺寸。在大多數情況下，這些預計僅具有一個元素，但是為更複雜的模型提供了額外的靈活性。如果提供多個選項，SDK將嘗試為DAW當前設置找到最佳的選項。每當採樣率或緩衝區大小與包裝器的DAW不同時，將自動觸發包裝器轉換為正確的採樣率或實現所需的緩衝區大小或兩者兼而有之的FIFO隊列。這將遭受少量的績效罰款，並增加一些延遲。如果模型與任何樣本率和/或緩衝尺寸兼容，則可以將這些列表空白。
這意味著保證do_forward_pass方法中的張量x具有形狀(1 if is_input_mono else 2, buffer_size)其中將在運行時從get_native_buffer_sizes Method中提供的buffer_size 。張量x還將以get_native_sample_rates方法中提供的列表中的採樣率之一。
我們提供了一個save_neutone_model助手輔助功能，可將模型保存到磁盤。默認情況下，這將將模型轉換為Torchscript，並通過一系列檢查運行，以確保插件可以加載它們。 The resulting model.nm file can be loaded within the plugin using the load your own button.在下面閱讀有關如何使用插件向每個人可見的默認集合的模型。
對於可以使用條件信號的型號，我們當前提供四個可配置的旋鈕參數。在上面定義的ClipperModelWrapper中，我們可以包括以下內容：
class ClipperModelWrapper ( WaveformToWaveformBase ):
...
def get_neutone_parameters ( self ) -> List [ NeutoneParameter ]:
return [ NeutoneParameter ( name = "min" , description = "min clip threshold" , default_value = 0.5 ),
NeutoneParameter ( name = "max" , description = "max clip threshold" , default_value = 1.0 ),
NeutoneParameter ( name = "gain" , description = "scale clip threshold" , default_value = 1.0 )]
def do_forward_pass ( self , x : Tensor , params : Dict [ str , Tensor ]) -> Tensor :
min_val , max_val , gain = params [ "min" ], params [ "max" ], params [ "gain" ]
x = self . model . forward ( x , min_val , max_val , gain )
return x在正向通過期間， params變量將是以下字典：
{
"min" : torch . Tensor ([ 0.5 ] * buffer_size ),
"max" : torch . Tensor ([ 1.0 ] * buffer_size ),
"gain" : torch . Tensor ([ 1.0 ] * buffer_size )
}字典的鍵在get_parameters函數中指定。
參數將始終在0到1之間，並且do_forward_pass函數可用於在運行模型的內部正向方法之前進行任何必要的重新驗證。
此外，該插件發送的參數以樣本級別的粒度出現。默認情況下，我們採用每個緩衝區的平均值並返回單個浮點（作為張量），但是aggregate_param方法可用於覆蓋聚合方法。有關保留此顆粒狀的示例，請參見完整的快船導出文件。
一些音頻模型會延遲一定量的樣本的音頻。這取決於每個特定模型的體系結構。為了使通過插件對齊的潮濕和乾信號，需要報告其模型誘導的延遲樣本。 calc_model_delay_samples可用於指定延遲樣本的數量。 Rave模型平均具有一個延遲的緩衝區（2048個樣本），該緩衝區在calc_model_delay_samples方法中靜態傳達，可以在示例中看到。用重疊ADD實現的模型將具有等於用於交叉載體的樣品數量的延遲，如Demucs模型包裝器或光譜濾波器示例所示。
計算模型添加的延遲可能很困難，尤其是因為可能需要組合多種不同的延遲來源（例如，cossfaded延遲，濾鏡延遲，lookahead緩衝液延遲和/或在未對齊的干和濕音頻的培訓的神經網絡） 。值得花一些額外的時間測試您的DAW模型，以確保正確報告延遲。
在模型中添加外觀緩衝區可能是有用的，對於需要一定量的其他上下文來輸出有用結果的模型。可以通過指示在get_look_behind_samples方法中可以輕鬆啟用lookbehind緩衝區。當此方法返回大於零的數字時， do_forward_pass方法將始終接收一個形狀張量(in_n_ch, look_behind_samples + buffer_size) ，但仍必須返回最新示例的形狀(out_n_ch, buffer_size)的張量。
我們建議在可能的情況下避免使用外觀緩衝區，因為它會使您的模型效率降低，並且在每次遠期傳球中可能會導致浪費的計算。如果使用純粹的捲積模型，請嘗試將所有捲積切換到緩存的捲積。
當在訓練分佈中出現的輸入外，AI模型通常以意想不到的方式行動。我們在neutone_sdk/filters.py文件中提供一系列常見的過濾器（低音，高通，頻段，頻段停止）。這些可以在向前傳遞期間使用，以限制進入模型的輸入的域。其中一些可以誘導少量延遲，查看示例/example_clipper_prefilter.py文件，以獲取有關如何設置過濾器的簡單示例。
該插件包含針對創建者的默認模型列表，這些模型希望在創作過程中使用它們。我們鼓勵用戶對獲得的結果感到滿意，以提交他們的模型，以便社區可以使用它們。為了提交，我們需要一些其他元數據，這些元數據將用於顯示有關針對創作者和其他研究人員的模型的信息。這將顯示在Neutons網站和插件內部。
跳過了先前的快船模型，這是一個基於由Micro-TCN啟發的隨機TCN超速模型的更現實的示例。
class OverdriveModelWrapper ( WaveformToWaveformBase ):
def get_model_name ( self ) -> str :
return "conv1d-overdrive.random"
def get_model_authors ( self ) -> List [ str ]:
return [ "Nao Tokui" ]
def get_model_short_description ( self ) -> str :
return "Neural distortion/overdrive effect"
def get_model_long_description ( self ) -> str :
return "Neural distortion/overdrive effect through randomly initialized Convolutional Neural Network"
def get_technical_description ( self ) -> str :
return "Random distortion/overdrive effect through randomly initialized Temporal-1D-convolution layers. You'll get different types of distortion by re-initializing the weight or changing the activation function. Based on the idea proposed by Steinmetz et al."
def get_tags ( self ) -> List [ str ]:
return [ "distortion" , "overdrive" ]
def get_model_version ( self ) -> str :
return "1.0.0"
def is_experimental ( self ) -> bool :
return False
def get_technical_links ( self ) -> Dict [ str , str ]:
return {
"Paper" : "https://arxiv.org/abs/2010.04237" ,
"Code" : "https://github.com/csteinmetz1/ronn"
}
def get_citation ( self ) -> str :
return "Steinmetz, C. J., & Reiss, J. D. (2020). Randomized overdrive neural networks. arXiv preprint arXiv:2010.04237."查看Core.py內部方法的文檔，以及網站和插件中的隨機超速模型，以了解將顯示每個字段的位置。
要提交模型，請在GitHub存儲庫上打開問題。我們目前需要以下內容：
model.nm file outputted by the save_neutone_model helper function SDK提供了三種CLI工具，可用於調試和測試包裝模型。
例子：
$ python -m neutone_sdk.benchmark benchmark-speed --model_file model.nm
INFO:__main__:Running benchmark for buffer sizes (128, 256, 512, 1024, 2048) and sample rates (48000,). Outliers will be removed from the calculation of mean and std and displayed separately if existing.
INFO:__main__:Sample rate: 48000 | Buffer size: 128 | duration: 0.014±0.002 | 1/RTF: 5.520 | Outliers: [0.008]
INFO:__main__:Sample rate: 48000 | Buffer size: 256 | duration: 0.028±0.003 | 1/RTF: 5.817 | Outliers: []
INFO:__main__:Sample rate: 48000 | Buffer size: 512 | duration: 0.053±0.003 | 1/RTF: 6.024 | Outliers: []
INFO:__main__:Sample rate: 48000 | Buffer size: 1024 | duration: 0.106±0.000 | 1/RTF: 6.056 | Outliers: []
INFO:__main__:Sample rate: 48000 | Buffer size: 2048 | duration: 0.212±0.000 | 1/RTF: 6.035 | Outliers: [0.213]
運行速度基準將以48000的樣本速率自動運行隨機輸入，緩衝尺寸為（128、256、512、1024、2048），並報告執行一個緩衝區推斷所需的平均時間。從中，計算出1/RTF ，它代表模型的速度快。隨著這個數字越高，該模型將在DAW中使用較少的資源。對於該數字，該數字必須大於1，才能在基準測試的計算機上實時執行。
測試的採樣率和緩衝尺寸以及內部重複基準的次數以計算平均值和用於計算的線程數量，可作為參數可用。運行python -m neutone_sdk.benchmark benchmark-speed --help以獲取更多信息。指定自定義樣本率或緩衝大小時，每個人都需要分別傳遞給CLI。例如： --sample_rate 48000 --sample_rate 44100 --buffer_size 32 --buffer_size 64 。
雖然速度基準應該很快，因為通常要說的是實時的，但如果模型太慢，則可能會卡住。確保選擇適當數量的採樣率和緩衝尺寸進行測試。
例子：
$ python -m neutone_sdk.benchmark benchmark-latency model.nm
INFO:__main__:Native buffer sizes: [2048], Native sample rates: [48000]
INFO:__main__:Model exports/ravemodel/model.nm has the following delays for each sample rate / buffer size combination (lowest delay first):
INFO:__main__:Sample rate: 48000 | Buffer size: 2048 | Total delay: 0 | (Buffering delay: 0 | Model delay: 0)
INFO:__main__:Sample rate: 48000 | Buffer size: 1024 | Total delay: 1024 | (Buffering delay: 1024 | Model delay: 0)
INFO:__main__:Sample rate: 48000 | Buffer size: 512 | Total delay: 1536 | (Buffering delay: 1536 | Model delay: 0)
INFO:__main__:Sample rate: 48000 | Buffer size: 256 | Total delay: 1792 | (Buffering delay: 1792 | Model delay: 0)
INFO:__main__:Sample rate: 44100 | Buffer size: 128 | Total delay: 1920 | (Buffering delay: 1920 | Model delay: 0)
INFO:__main__:Sample rate: 48000 | Buffer size: 128 | Total delay: 1920 | (Buffering delay: 1920 | Model delay: 0)
INFO:__main__:Sample rate: 44100 | Buffer size: 256 | Total delay: 2048 | (Buffering delay: 2048 | Model delay: 0)
INFO:__main__:Sample rate: 44100 | Buffer size: 512 | Total delay: 2048 | (Buffering delay: 2048 | Model delay: 0)
INFO:__main__:Sample rate: 44100 | Buffer size: 1024 | Total delay: 2048 | (Buffering delay: 2048 | Model delay: 0)
INFO:__main__:Sample rate: 44100 | Buffer size: 2048 | Total delay: 2048 | (Buffering delay: 2048 | Model delay: 0)運行速度基準將自動計算sample_rate=(44100, 48000)和buffer_size=(128, 256, 512, 1024, 2048)的模型的延遲。這概述了通用DAW設置將會發生什麼。總延遲分為緩衝延遲和模型延遲。該模型延遲由模型包裝器中的模型的創建者報告，如上所述。 The buffering delay is automatically computed by the SDK taking into consideration the combination of (sample_rate, buffer_size) specified by the wrapper (the native ones) and the one specified by the DAW at runtime.在其本機(sample_rate, buffer_size)組合中運行該模型將產生最小延遲。
與上面的速度基準類似，可以從CLI指定(sample_rate, buffer_size)的測試組合。運行python -m neutone_sdk.benchmark benchmark-latency --help以獲取更多信息。
$ python -m neutone_sdk.benchmark profile --model_file exports/ravemodel/model.nm
INFO:__main__:Profiling model exports/ravemodel/model.nm at sample rate 48000 and buffer size 128
STAGE:2023-09-28 14:34:53 96328:4714960 ActivityProfilerController.cpp:311] Completed Stage: Warm Up
30it [00:00, 37.32it/s]
STAGE:2023-09-28 14:34:54 96328:4714960 ActivityProfilerController.cpp:317] Completed Stage: Collection
STAGE:2023-09-28 14:34:54 96328:4714960 ActivityProfilerController.cpp:321] Completed Stage: Post Processing
INFO:__main__:Displaying Total CPU Time
INFO:__main__:-------------------------------- ------------ ------------ ------------ ------------ ------------ ------------ ------------ ------------
Name Self CPU % Self CPU CPU total % CPU total CPU time avg CPU Mem Self CPU Mem # of Calls
-------------------------------- ------------ ------------ ------------ ------------ ------------ ------------ ------------ ------------
forward 98.54% 799.982ms 102.06% 828.603ms 26.729ms 0 b -918.17 Kb 31
aten::convolution 0.12% 963.000us 0.95% 7.739ms 175.886us 530.62 Kb -143.50 Kb 44
...
...
Full output removed from GitHub.
分析工具將以48000的樣本速率和Pytorch Profiler下的128個緩衝尺寸運行模型，並輸出一系列見解，例如總CPU時間，總CPU存儲器使用情況（每個功能）和分組的CPU存儲器使用情況（通過一組功能調用）。這可以用於識別模型代碼中的瓶頸（即使在do_forward_pass調用中的模型調用中，也可以在模型代碼中識別瓶頸。
與基準測量類似，可以以樣本速率和緩衝尺寸的不同組合以及不同數量的線程進行運行。運行python -m neutone_sdk.benchmark profile --help以獲取更多信息。
我們歡迎對SDK的任何貢獻。請盡可能添加類型，並使用black格式化器以備可讀性。
當前的路線圖是：
Audocitorch項目是SDK開發的主要靈感。在這裡查看
