JUCEハンズオン2023 〜JUCEをはじめよう〜

Last updated at 2023-12-01Posted at 2023-11-30

本記事はJUCE Advent Calendar 2023 の12月1日向けに投稿した記事です。

はじめに

本記事は過去に投稿したJUCEハンズオン2021 〜JUCEをはじめよう〜の改訂版になります。
過去の記事をベースに、2023年時点での情報を記載しております。
そのため、過去の記事と内容が重複する箇所があることをあらかじめご了承ください。

対象とするバージョン

JUCE 7.0.9
Visual Studio 2022
Xcode 14.2
CMake 3.25以上
Git 2.3以上

JUCEについて

JUCE (Jules' Utility Class Extensions)は、C++言語によるマルチメディア系アプリケーションの開発を支援するフレームワークです。
JUCEフレームワークは次の要素によって構成されます。

JUCEライブラリ：C++言語で記述されたクロスプラットフォーム設計のライブラリ
Projucer：JUCE専用のプロジェクトジェネレータ、ソースファイルやビルド設定等を管理し、各種IDE(VisualStudio, Xcode, Makefile)向けにプロジェクトファイルを出力する
CMakeモジュール：JUCEライブラリをCMakeプロジェクトにインテグレーションするためのモジュールであり、Projucerと同等の機能（リソースのバイナリ化等）も提供する

上記ライブラリ、プロジェクトジェネレータを利用してプロジェクトを構築し、各プラットフォーム用のC++開発環境でビルドすることで、ワンソースからWindows, macOS, Linux, iOS, Android で動作するアプリケーションを作成することができます。
公式サイト

JUCEの特徴

JUCEの最大の特徴として、オーディオプラグインを開発するためのテンプレートが充実していることが挙げられます。VST3/AudioUnit/AAX/LV2/ARAプラグインといった、DTMユーザーにはお馴染みとなっているプラグインフォーマットをワンソースから開発することが挙げられます。効率良くオーディオプラグインを開発できることから、日本国内外で多くの採用事例があります。
公式サイトによる採用事例の紹介

JUCEライブラリと Projucer

JUCEフレームワークは、各種機能のC++ APIを提供する『JUCEライブラリ』と、各種プラットフォーム向けのプロジェクトを出力するジェネレータ『Projucer』によって構成されます。
『JUCEライブラリ』には機能別に『モジュール』という単位で構成が分かれており、『Projucer』はプロジェクトに必要なモジュールを取り込んで、IDE用のプロジェクトファイルやビルドスクリプトに紐付ける作業を担当します。

JUCEライブラリと CMake

2020年にリリースされたJUCE 6から、ビルドマネジメントツール『CMake』のサポートが追加されました。

『CMake』とは、主にC言語、C++言語などC系言語のビルドにおけるクロスプラットフォームビルド環境を提供するビルドマネジメントツールの一つです。様々なプロジェクトに採用されており、大きなエコシステムを形成しています。

JUCEがCMakeをサポートすることで以下のメリットを得ることができるようになりました。

ビルド設定をCMake用のフォーマットで記述することができる
CMakeのエコシステムの恩恵を受けることができる
CMakeが独自に提供する機能を利用することができる
CMakeに対応した他のライブラリとのインテグレーションが容易になる
Projucerの使い方を習得する必要がなくなる

JUCEモジュール一覧

JUCEライブラリは、モジュールという単位で機能別にAPIが別れており、オーディオデバイスとの接続を処理するモジュールや、オーディオプラグインフォーマットの定義を持つモジュール、オーディオファイルを読み込む機能を持つモジュール、OSC（Open Sound Control）の機能を抽象化したモジュールなどが含まれています。

以下がJUCEライブラリのモジュール一覧です。(JUCE 7.0.9時点)

モジュール名	提供する機能
juce_analytics	ユーザーの利用情報を収集して送信するクラス
juce_audio_basics	オーディオバッファの操作、MIDIメッセージ処理、シンセサイザーなどのクラス
juce_audio_devices	オーディオインターフェースおよびMIDIインターフェースの制御や、再生と録音をするクラス
juce_audio_formats	さまざまなオーディオファイル形式を読み込み・書き込みするクラス
juce_audio_plugin_client	VST、VST3、AudioUnit、AAX、LV2、ARAプラグインを構築するためのクラス
juce_audio_processors	VST、AU、または内部で生成されたオーディオプロセッサのロードおよび再生をするクラス
juce_audio_utils	オーディオ関連のGUIおよびその他のタスク（MIDI over BLE含む）を処理するクラス
juce_box2d	Box2D物理エンジンといくつかのユーティリティクラス
juce_core	JUCEモジュールの基盤となる基本クラスやAPIを含む必須セット、コアモジュール
juce_cryptography	RSA、Blowfish、MD5、SHAなどのさまざまな基本暗号化機能を持つクラス
juce_data_structures	variantなデータ型を提供する、アンドゥ/リドゥなどを管理する、スマートなデータ構造を操作するクラス
juce_dsp	オーディオバッファ操作、デジタルオーディオ処理、フィルタリング、オーバーサンプリング、数学関数などを高速に実行するクラス
juce_events	アプリケーションのメインイベントループを実行し、メッセージ、タイマーなどを送受信するためのクラス
juce_graphics	2Dベクトルグラフィックス、画像読み込み/保存、フォント処理などをするためのクラス
juce_gui_basics	基本的なユーザーインターフェイスを作成するコンポーネントおよび関連するクラス
juce_gui_extra	特別なタスクを処理するためのGUIクラス拡張
juce_opengl	JUCEウィンドウでOpenGLをレンダリングするためのクラス
juce_midi_ci	MIDI 2.0規格に含まれるMIDI Capability Inquiry (MIDI-CI)規格を実装するためのクラス
juce_osc	OSC(Open Sound Control)を実装したクラス
juce_product_unlocking	オンライン製品認証を実装するクラス
juce_video	ビデオ再生と、カメラ入力をキャプチャするためのクラス

また、JUCEモジュールのフォーマットがパブリックになっているので、ユーザーが独自のJUCEモジュール（3rd party JUCE module）を構築することが可能です。

ライセンスについて

ライセンスの詳細は公式サイトのEULAをご参照ください。公式: JUCE 7 EULA
JUCEには複数のライセンスオプションが用意されており、ユーザーの事情に応じて選択することができます。

■ライセンスオプション一覧

Personal
Indie
Pro
Educational
GPL v3

特筆すべき点として、無料で利用することができるPersonalライセンスとGPL v3ライセンスが設定されています。
ただし、Personalライセンスを利用するには、以下の条件を満たす必要があります。

起動時のスプラッシュスクリーンを表示することに同意すること。
アプリケーションの利用情報を送信することに同意すること。
年間の収入または資本金額が$50k未満であること。

上記の利用条件を満たさない場合には、JUCE 7 End User License Agreement の 1.9.に記載されている通り、有償ライセンスを購入する若しくはGPLライセンスが適用される点には注意しておいた方がいいでしょう。
プロジェクト自体をオープンソースにすることでコミュニティの支援を受けたい、教育目的でソースコードを開示したいなど、GPLv3を選択することが好ましい場合もあるので、開発目的に合わせてライセンスを選択すると良いでしょう。

ライセンスタイプ	JUCE Personal	JUCE Indie	JUCE Pro	Education	GPL v3
スプラッシュスクリーン	“made with JUCE” 表示必須	非表示可	非表示可	“made with JUCE” 表示必須	-
年間の収入または資本金額の限度	$50k	$500k	-	-	-
サブスクリプション最低契約期間	-	1ヵ月	1ヵ月	-	-
サブスクリプションライセンス料金	-	$40/月	$130/月	-	-
永続ライセンス料金	-	$800	$2,600	-	-

JUCEライブラリはオープンソース

JUCEはGitHub上のGitリポジトリで開発が行われており、ソースコードも全て開示されています。IssueやPull requestを送ることで不具合報告や機能改善の要望、修正の提案などのプロジェクトに貢献することができます。また、developブランチをチェックアウトすることで、将来的に実装される機能を試すこともできます。

Gitリポジトリ: juce-framework/JUCE

JUCEをはじめよう[Projucer版]

ここでは、Projucerを使用する方法でJUCE DemoRunnerをビルドするまでの手順について示します。

開発環境のセットアップ

JUCEを使用したC++プロジェクトを実行可能なプログラムにコンパイルするには、C++言語の開発環境（コンパイラ、ビルドツール等）をセットアップする必要があります。

Windows
- Visual Studio 2022をインストールする
  - IDE本体をインストールする
  - C++開発環境を追加インストールする
macOS
- Xcodeをインストールする
  - AppStoreまたはDeveloper Programから入手してください

JUCEを入手する

JUCEを入手するには、大きく2つの方法があります。

公式サイトからダウンロード
GitHub上のGitリポジトリをクローン

上記のうち、入門者には『公式サイトからダウンロード』する方法をお勧めします。
『GitHub上のGitリポジトリをクローン』する方法では、Projucerを開発環境でセルフビルドする手間がかかります。

A. 公式サイトからダウンロード

JUCE公式サイトのダウンロードページにアクセス

URL: https://www.juce.com/get-juce

サイト内の[Download]をクリックします

プラットフォームごとに用意されたリンクからダウンロードします

プラットフォーム用にビルド済みのProjucerが同梱されています

B. GitHub上のGitリポジトリをクローン

Gitリポジトリをローカル環境にクローンする


$ git clone https://github.com/juce-framework/JUCE.git

Projucerをセルフビルドする

以下のディレクトリに置かれたIDE向けプロジェクトから Projucer をセルフビルドしてください。
ディレクトリ: JUCE/extras/Projucer/Builds/(プラットフォームまたはIDE名)

Projucerのセットアップ

ここでは、Projucerからアプリケーションプロジェクトを作成するまでのセットアップの手順について示します。

Projucerを起動する

初回起動時には、プロジェクト制作画面が表示されます

Licenseのセッティング

※Personal版で使用する場合はアカウントの作成は不要です

Projucerを起動する
[File]→[Sign in...]メニューをクリックしてダイアログを開く
アカウントを持っていない場合、[Create an account]をクリックして遷移したWebサイトにてJUCEアカウントを作成する
JUCEアカウントを入力してサインインする
Webサイト上で購入したJUCEライセンス（Indie, Pro）は、サインインすることでProjucerに反映されます

JUCEライブラリのPath設定

Projucerを起動する
[File]→[Global Paths...]メニューをクリックして『Global paths』ダイアログを開く
[Path to JUCE]欄にJUCEのルートディレクトリのパスを入力する（入力欄横の[...]をクリックするとファイルダイアログが開きます）

公式サイトからDLした場合はZIPの解凍先ディレクトリ
git cloneした場合はリポジトリのルートディレクトリ

[JUCE Modules]欄にJUCEディレクトリの直下に置かれた『modules』ディレクトリのパスを入力する

■ Projucerのメニューから[Global Paths...]を選択する

↓

■ JUCEのルートディレクトリとmodulesディレクトリを設定する

JUCE DemoRunnerのビルドと実行

JUCEライブラリのパッケージに含まれているデモアプリケーション『JUCE DemoRunner』をビルドすることができれば、JUCEとProjucerのセットアップは完了です。

Projucerのメニューから[File]→[Open Example]→[Launch Demo Runner]をクリック
- 公式サイトからDLした場合、ビルド済みのDemoRunnerバイナリが同梱されているため、ビルドをスキップしてDemoRunnerが起動する
- git cloneした場合、DemoRunnerを新規にビルドする必要がある。ProjucerからIDEでプロジェクトを開くかどうか尋ねられるので、それにしたがってプロジェクトを開いてビルドを実行する
DemoRunnerの実行ファイルの用意が済んだら、Projucerの[File]→[Open Example]→[Launch Demo Runner]からDemoRunnerを起動する

■ Projucerのメニューから[Launch Demo Runner]を選択する

↓ ビルド実行後に起動 or ビルド不要の場合はそのまま起動

■ JUCE DemoRunner
DemoRunnerのブラウジングメニューから様々なデモプログラムを起動してみましょう。
各デモプログラムからJUCEライブラリのリファレンス実装を確認することができます。

JUCEをはじめよう[CMake版]

ここでは、CMakeを使用してJUCE DemoRunnerをビルドするまでの手順について示します。
本記事では、CMakeの使い方およびAPI仕様についての詳細は解説しない点についてご了承ください。

開発環境のセットアップ

Windows
- Visual Studio 2022をインストールする
  - IDE本体をインストールする
  - C++開発環境を追加インストールする
- CMakeをインストールする
  - ダウンロードページから入手してインストールする公式サイト
  - CMakeのパスを環境変数に追加する
macOS
- Xcodeをインストールする
  - AppStoreまたはDeveloper Programから入手してください
- CMakeをインストールする
  - Homebrewまたはダウンロードページから入手してインストールする公式サイト
  - CMakeのパスを環境変数に追加する

JUCEを入手する

この項目はProjucer版の説明と共通です。

公式サイトからダウンロード
GitHub上のGitリポジトリをクローン

JUCE DemoRunnerのビルドと実行

Windows - Visual Studio 2022 の場合

コマンドプロンプトから以下のコマンドを実行してJUCE DemoRunnerをビルドします

REM JUCEディレクトリに移動する
cd (JUCEディレクトリの置かれた場所)/JUCE

REM CMakeのconfigureとgenerateを実行する
REM この時カレントディレクトリ直下に"build"ディレクトリを作成する
cmake -G "Visual Studio 17 2022" -B build -DJUCE_BUILD_EXAMPLES=ON

REM "build"ディレクトリ内に生成されたDemoRunnerプロジェクトのビルドを実行する
cmake --build build --target DemoRunner

JUCE/build/examples/DemoRunner/DemoRunner_artefacts/Debugディレクトリに実行ファイルDemoRunner.exeが生成されます。この実行ファイルを起動すると、JUCE DemoRunnerが立ち上がります。

macOS - Xcode の場合

ターミナルから以下のコマンドを実行してJUCE DemoRunnerをビルドします

# JUCEディレクトリに移動する
$ cd (JUCEディレクトリの置かれた場所)/JUCE

# CMakeのconfigureとgenerateを実行する
# この時カレントディレクトリ直下に"build"ディレクトリを作成する
$ cmake -G Xcode -B build -DJUCE_BUILD_EXAMPLES=ON

# "build"ディレクトリ内に生成されたDemoRunnerプロジェクトのビルドを実行する
$ cmake --build build --target DemoRunner

JUCE/build/examples/DemoRunner/DemoRunner_artefacts/Debugディレクトリに実行ファイルDemoRunner.appが生成されます。この実行ファイルを起動すると、JUCE DemoRunnerが立ち上がります。

JUCEでHello Sinewave!

JUCEアプリケーションの開発環境が整ったら、簡単なアプリケーションを作成してみましょう。
今回は、サイン波を鳴らす処理を実装するオーディオプログラミング版 Hello world! を作成します。

プロジェクト作成からコード編集まで [Projucer版]

新規プロジェクトを作成する

Projucerを起動したら、[File]→[New Project...]をクリックして、新規プロジェクト作成画面を表示します。
今回は [Application]→[Audio] テンプレートを選択します。

新規プロジェクト作成画面の[Exporters]の項目を確認します。ターゲットとするプラットフォームに合わせてチェックを入れます。

macOSでの開発なら、Xcodeにチェックを入れます。
Windowsでの開発なら、VisualStudioにチェックを入れます（2022, 2019, 2017をサポート）。
Linuxでの開発なら、Linux Makefileにチェックを入れます。

新規プロジェクト作成画面の[Create Project]ボタンをクリックします。プロジェクトの保存先を選択するダイアログが開くので、保存先を選択してください。

新規プロジェクトを作成すると、"Main.cpp","MainComponent.h","MainComponent.cpp"の3つのソースファイルが作成されます。

プロジェクトの保存とIDEを開く

Projucerで新規プロジェクトの保存と、IDE（VisualStudio、Xcode）でプロジェクトを開きます。

Projucer上部のコンボボックスから、起動したいIDEを選択します。
IDEのアイコンが表示されているボタンをクリックします。
プロジェクトの保存とIDEの起動が行われます。

プロジェクト作成からコード編集まで [CMake版]

CMakeを使用してJUCEアプリケーションを作る場合、ソースファイルの作成や、ビルド設定の記述をCMakeLists.txtに記述していく作業を開発者自身で行う必要があります。
そのため、Projucerでプロジェクトを新規作成する場合と比べると、プロジェクトの最小の構成を組み上げるまでの手順が増えることになります。
本記事ではその手順については割愛し、私が作成した最小構成のCMake向けテンプレートを使用して説明をしていきます。

筆者作成のテンプレートを git clone する

筆者が作成したオーディオアプリケーションのテンプレートを以下のGitリポジトリに配置しました。
コマンドプロンプトやターミナルから次のコマンドを実行して、GitリポジトリのクローンとGitサブモジュールの初期化を実行してください。
Gitリポジトリ: juce_hands-on_2023.git

# Gitリポジトリのクローンと併せて内部のGitサブモジュールもクローンする
$ git clone --recursive https://github.com/COx2/juce_hands-on_2023.git

プロジェクトのファイル構成について

このテンプレートは以下のファイル構成になっています。
Sourceディレクトリに置かれたソースコードは、Projucer版の項目で説明したものと同一のファイルとなっています。

juce_hands-on_2023/
　├ External/
  │  └ JUCE/  # Gitサブモジュールとして取り込んだJUCEリポジトリ
　├ Source/   # プロジェクトのソースコードを配置するディレクトリ
  │  ├ Main.cpp
  │  ├ MainComponent.h
  │  └ MainComponent.cpp
　├ CMakeLists.txt  # CMakeで実行するビルド設定を記述するテキストファイル
　└ LICENSE

上記のファイルのうち、CMakeLists.txtは以下の記述となっています。
CMakeのプロジェクトからJUCEライブラリを取り込むことで、JUCEライブラリ内に含まれるCMakeモジュールが読み込まれ、JUCE CMake APIが使えるようになります。
JUCE CMake APIについては JUCE/docs/CMake API.md にドキュメントが用意されています。

# CMakeの最低バージョンを特定する
cmake_minimum_required(VERSION 3.15)

# C++に関するオプション設定
enable_language(CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

# プロジェクト名を決定する
project(NewProject VERSION 1.0.0)

# JUCEライブラリの場所を特定する
# JUCEライブラリ内に含まれるCMakeモジュールが読み込まれ、JUCE CMake APIが使えるようになる
add_subdirectory(External/JUCE)

# GUIアプリケーション版のJUCEプロジェクトを追加する
# プロジェクト名は"NewProject"にする
juce_add_gui_app(NewProject
    PRODUCT_NAME "NewProject")

# "NewProject"のソース上で"#include <JuceHeader.h>"によるJUCEライブラリのインクルードを可能にする
juce_generate_juce_header(NewProject)

# "NewProject"にC++ソースファイルを追加する
target_sources(NewProject
    PRIVATE
        Source/Main.cpp
        Source/MainComponent.h
        Source/MainComponent.cpp)

# "NewProject"に適用するコンパイル定義を設定する
target_compile_definitions(NewProject
    PRIVATE
        JUCE_APPLICATION_NAME_STRING="$<TARGET_PROPERTY:NewProject,JUCE_PRODUCT_NAME>"
        JUCE_APPLICATION_VERSION_STRING="$<TARGET_PROPERTY:NewProject,JUCE_VERSION>")

# "NewProject"にリンクするライブラリを決定する
target_link_libraries(NewProject
    PRIVATE
        juce::juce_audio_utils
    PUBLIC
        juce::juce_recommended_config_flags
        juce::juce_recommended_lto_flags
        juce::juce_recommended_warning_flags)

CMakeのconfigureとgenerateを実行する

コマンドプロンプトやターミナルから次のコマンドを実行すると、CMakeのconfigureとgenerateが実行され、IDE用のプロジェクトが生成されます。
なお、CMake --buildコマンドを実行することでコマンドラインからビルドを実行することもできます。

Windows - Visual Studio 2022 の場合

REM リポジトリのディレクトリに移動する
cd (リポジトリが置かれた場所)/juce_hands-on_2023

REM CMakeのconfigureとgenerateを実行する
REM この時カレントディレクトリ直下に"build"ディレクトリを作成する
cmake -G "Visual Studio 17 2022" -B build

REM "build"ディレクトリ内に生成されたプロジェクトのビルドを実行する
cmake --build build

macOS - Xcode の場合

# リポジトリのディレクトリに移動する
$ cd (リポジトリが置かれた場所)/juce_hands-on_2023

# CMakeのconfigureとgenerateを実行する
# この時カレントディレクトリ直下に"build"ディレクトリを作成する
$ cmake -G Xcode -B build

# "build"ディレクトリ内に生成されたプロジェクトのビルドを実行する
$ cmake --build build

IDEでプロジェクトを開く

CMakeのconfigureとgenerateを実行すると、juce_hands-on_2023/buildディレクトリにIDE向けのプロジェクトファイルが生成されます。プロジェクトファイルをIDEで開くことで、IDE上でソーコードの編集を始めることができます。

サイン波を鳴らすプログラムを実装する

プロジェクト内のソースコードを編集して、サイン波を鳴らす処理を実装してみましょう。
MainComponent.cppにある関数void getNextAudioBlock (const AudioSourceChannelInfo& bufferToFill) overrideの内部実装を以下のように編集します。

#include "MainComponent.h"

~~~中略~~~

void MainComponent::getNextAudioBlock (const juce::AudioSourceChannelInfo& bufferToFill)
{
    bufferToFill.clearActiveBufferRegion();

    const float level = 0.5f;

    auto* buffer = bufferToFill.buffer;
    for (int channel = 0; channel < buffer->getNumChannels(); channel++)
    {
        float* channelData = buffer->getWritePointer(channel);

        for (int sample = 0; sample < buffer->getNumSamples(); sample++)
        {
            channelData[sample] = std::sin(juce::MathConstants<float>::twoPi * sample / buffer->getNumSamples() * 2) * level;
        }
    }
}
~~~中略~~~