sOURnd 문서 내 엔진
이 페이지에서
  1. 제공되는 것
  2. 1. 모듈과 라이브러리 추가
  3. 2. 엔진, 파라미터, 브리지 만들기
  4. 3. 엔진 고르기
  5. 알아 둘 규칙
  6. 제한
  7. 플랫폼
  8. 라이선스

JUCE 빠른 시작

JUCE 8 플러그인에 sournd 엔진을 추가하세요. CMake 세 줄, C++ 객체 세 개, 내 컴퓨터에 Rust 툴체인은 필요 없어요.

  1. 다운로드JUCE 모듈과 내 엔진 라이브러리
  2. CMake세 줄
  3. C++ 객체 세 개엔진, 파라미터, 브리지
  4. 내 플러그인평소처럼 JUCE로 빌드

제공되는 것

  • sournd_engine은 juce_audio_processors와 juce_dsp에만 의존하는 표준 JUCE 모듈이에요(Apache-2.0). 다운로드: sournd-engine-juce-module.zip.
  • 플랫폼용 정적 라이브러리(libsournd_cabi.a, Windows에서는 sournd_cabi.lib)와 헤더 sournd_engine.h. 무료 엔진은 아무 무료 엔진 페이지(https://sournd.com/download/free/macos, https://sournd.com/download/free/linux, https://sournd.com/download/free/windows)에서, 유료 엔진은 내 엔진에서 받으세요.
  • juce::dsp::ProcessorBase를 구현하는 SourndEngine, 그리고 엔진으로 APVTS 레이아웃을 만들고 둘을 동기화해 주는 SourndEngineParameters.

1. 모듈과 라이브러리 추가

모듈의 압축을 풀어 sournd_engine 폴더를 만들고, 그 옆에 엔진 다운로드의 압축도 푸세요.

cmake
juce_add_module(path/to/sournd_engine)
target_include_directories(MyPlugin PRIVATE path/to/include)            # sournd_engine.h
target_link_libraries(MyPlugin PRIVATE sournd_engine path/to/libsournd_cabi.a)

유니버설 macOS 플러그인은 -DCMAKE_OSX_ARCHITECTURES='arm64;x86_64'로 빌드하고 유니버설 아카이브를 링크하세요.

Linux에서는 다운로드에 아키텍처별로 아카이브가 하나씩 들어 있어요. 빌드하는 머신에 맞는 것을 고르고 필요한 시스템 라이브러리를 추가하세요:

cmake
if(CMAKE_SYSTEM_PROCESSOR MATCHES "aarch64|arm64")
  set(SOURND_ARCH linux-aarch64)
else()
  set(SOURND_ARCH linux-x86_64)
endif()
target_link_libraries(MyPlugin PRIVATE sournd_engine
    path/to/lib/${SOURND_ARCH}/libsournd_cabi.a pthread dl m)

2. 엔진, 파라미터, 브리지 만들기

메시지 스레드에서 이 순서대로 만드세요:

cpp
#include <sournd_engine/sournd_engine.h>

class MyPlugin final : public juce::AudioProcessor
{
public:
    MyPlugin()
        : AudioProcessor (BusesProperties().withInput ("Input", juce::AudioChannelSet::stereo())
                                           .withOutput ("Output", juce::AudioChannelSet::stereo())),
          engine ("org.sournd.reverb.roomette"),
          parameters (*this, nullptr, "Parameters", sournd::SourndEngineParameters::createLayout (engine)),
          bridge (engine, parameters)
    { jassert (engine.isValid()); }

    void prepareToPlay (double rate, int maximumBlock) override
    {
        engine.prepare ({ rate, (juce::uint32) maximumBlock, (juce::uint32) getTotalNumOutputChannels() });
        bridge.prepare (rate);
        setLatencySamples ((int) engine.latency());
    }

    void processBlock (juce::AudioBuffer<float>& buffer, juce::MidiBuffer&) override
    {
        bridge.apply ((uint32_t) buffer.getNumSamples());
        juce::dsp::AudioBlock<float> block { buffer };
        engine.process (juce::dsp::ProcessContextReplacing<float> { block });
    }

    void getStateInformation (juce::MemoryBlock& destination) override
    {
        // Hosts can ask for state during playback: JUCE's callback lock keeps processBlock out
        // while the engine is read (the C ABI allows one call at a time per engine).
        const juce::ScopedLock lock (getCallbackLock());
        bridge.syncToEngine();
        destination = engine.saveState();
    }

    void setStateInformation (const void* data, int bytes) override
    {
        if (bytes < 0) return;
        const juce::ScopedLock lock (getCallbackLock());
        if (engine.loadState (data, (size_t) bytes)) bridge.syncFromEngine();
    }

    double getTailLengthSeconds() const override { return engine.tailSeconds(); }

private:
    sournd::SourndEngine engine;
    juce::AudioProcessorValueTreeState parameters;
    sournd::SourndEngineParameters bridge;
};

실행 중에 일어나는 일:

블록마다

  1. 호스트노브와 오토메이션
  2. APVTS플러그인의 파라미터
  3. bridge.apply바뀐 값, 블록마다 한 번
  4. engine.process샘플 단위로 스무딩
  5. 오디오 출력

저장

  1. 호스트가 상태를 요청
  2. getCallbackLock()processBlock이 끼어들지 못하게 해요
  3. bridge.syncToEngine()
  4. engine.saveState()불투명한 블롭

불러오기

  1. 호스트가 상태를 돌려줌
  2. getCallbackLock()
  3. engine.loadState()파라미터 id로 맞춤
  4. bridge.syncFromEngine()

3. 엔진 고르기

카탈로그나 catalog.json에서 아무 id나 고르세요. 알 수 없는 id는 무음을 출력하는 잘못된 엔진을 만들어요. 그러니 isValid()와 lastError()를 확인하세요.

알아 둘 규칙

  • 파라미터 id는 안정적인 십진수 문자열이에요. 엔진 매니페스트에서 그 파라미터가 놓인 위치이고, 모든 엔진 페이지에 나와 있어요. 파라미터는 추가만 되고 번호가 다시 매겨지는 일은 없어요.
  • 호스트 범위는 각 파라미터의 테이퍼를 따라요. 로그 파라미터(cutoff, time, ratio)는 호스트의 0에서 1을 min * (max / min)^p로 매핑해요. 그래서 오토메이션 레인과 범용 에디터도 엔진 자체 노브처럼 같은 비율로 움직여요. 이미 선형 범위로 플러그인을 출시했다면 createLayout (engine, false)를 넘겨서 그대로 유지하세요. 호스트는 오토메이션을 0에서 1 사이의 값으로 저장하기 때문이에요.
  • bridge.apply는 블록이 시작될 때 바뀐 값을 엔진에 넘겨요. 엔진은 연속 컨트롤을 직접 샘플 단위로 스무딩하므로 소리는 호스트의 블록 크기에 좌우되지 않아요(1, 32, 64, 512프레임에서 비트 단위로 테스트했어요). 단계형과 불리언 컨트롤은 즉시 바뀌어요.
  • 호출당 프레임 수는 prepare에 넘긴 최대값 안에 들어가야 해요. 래퍼는 호스트 블록을 나누지 않아요.
  • 상태는 불투명하고 엔진 id에 묶여 있어요. 설정을 저장하며, 딜레이나 필터의 이력은 저장하지 않아요. 엔진 버전이 달라도 이전돼요. 값은 파라미터 id로 맞추고, 세션을 저장한 뒤에 추가된 파라미터는 기본값을 쓰고, 더 새로운 엔진의 값 중 이 엔진에 없는 것은 무시해요(lastStateReport()가 두 경우를 모두 세어요). 다른 엔진의 상태이거나 손상된 경우에만 거부하며, 이때는 아무것도 바뀌지 않아요.
  • 오디오 스레드는 메모리를 할당하거나, 락을 잡거나, 메시지 매니저를 호출하지 않아요. 처리 스레드마다 엔진 인스턴스를 하나씩 쓰세요.
  • 한 엔진에 대한 호출은 겹치면 안 돼요. processBlock 밖에서 엔진을 건드리는 모든 것(상태 저장과 불러오기, prepare, reset)은 위에서처럼 getCallbackLock()을 잡아서, 오디오를 처리하는 동안에는 실행되지 않게 하세요.

제한

현재 브리지의 한계예요.

  • 오디오는 32비트 float예요. 브리지는 float 버퍼만 처리해요. supportsDoublePrecisionProcessing()은 기본값(false)으로 두세요. 그러면 호스트가 플러그인에 float 오디오를 넘겨요.
  • 모노 또는 스테레오, 입력과 출력이 같아야 해요. 메인 채널은 하나 또는 둘이에요. 모노에서 스테레오, 스테레오에서 모노, 서라운드 레이아웃은 지원하지 않아요. 일부 엔진은 스테레오에서만 작동하니 가정하지 말고 isBusesLayoutSupported에서 엔진에 물어보세요(아래). supportsChannels는 임시 인스턴스를 준비하므로, 오디오 스레드에서 호출하지 말고 결과를 캐시하세요.
  • 사이드체인 엔진은 연결 안 됨, 모노, 스테레오 보조 입력을 받아요.
  • MIDI. 이펙트는 MIDI 버퍼를 무시하고, 브리지는 MIDI를 만들지 않아요. 악기 엔진은 모든 채널에서 note on, note off, all notes off(CC 120과 123)를 샘플 위치에 맞춰 읽어요. 피치 벤드, 애프터터치, 다른 컨트롤러, MPE는 전달되지 않아요.
  • 샘플레이트는 8 kHz에서 768 kHz까지, 블록당 최대 1,048,576프레임이에요.
  • 숨겨진 엔진 파라미터는 엔진의 상태 안에 남고 호스트 컨트롤로는 노출되지 않아요.
cpp
bool isBusesLayoutSupported (const BusesLayout& layout) const override
{
    const auto& in = layout.getMainInputChannelSet();
    return in == layout.getMainOutputChannelSet()
        && ((in == juce::AudioChannelSet::mono() && mono) || (in == juce::AudioChannelSet::stereo() && stereo));
}
// members, after engine:
const bool mono = engine.supportsChannels (1), stereo = engine.supportsChannels (2);

플랫폼

다운로드는 macOS 유니버설(arm64와 x86_64), Linux(x86_64와 aarch64, glibc 2.36 이상), Windows x64(MSVC)용으로 빌드돼요. 내 엔진 페이지에서 다운로드할 때 플랫폼을 고르세요. 에이전트는 platform=linux 또는 platform=windows-x64로 요청해요.

Windows에서는 zip에 sournd_cabi.lib가 두 개 들어 있어요. 동적 C 런타임(/MD, MSVC 기본값)을 쓰는 프로젝트는 lib/windows-x64/, 정적 런타임(/MT)은 lib/windows-x64-static-crt/예요. 플러그인에 맞는 쪽을 링크하고, 이어서 kernel32 ntdll userenv ws2_32 dbghelp를 링크하세요. zip의 README에 CMake 줄이 있어요.

라이선스

JUCE 모듈과 C 헤더는 Apache-2.0이어서 GPL이나 상용 JUCE 프로젝트에 링크할 수 있어요. JUCE 자체에는 별도의 라이선스와 플랜이 있고 sournd 라이선스는 이를 포함하지 않아요. JUCE 8 라이선스를 따르고, 출시하는 제품에 맞는 JUCE 플랜을 고르세요. 유료 엔진은 클로즈드 정적 라이브러리로 제공돼요. 라이선스를 보세요.