MENU

.NET MAUI iOSのAudioToolbox未定義シンボルとFFmpeg連携のリンクエラー完全解決ガイド

C#

「.NET MAUI の iOS ビルドにネイティブ静的ライブラリを含めたら、AudioToolbox まわりの未定義シンボルで止まる」――この現象は、プロジェクト設定とリンカの最終挙動を正しく理解できていれば、短時間で確実に解決できます。本稿では、_AudioServicesCreateSystemSoundID をはじめとする AudioToolbox の未定義シンボル問題の根本原因と再発を防ぐ設定を、実プロジェクト向けの具体例・検証コマンドとともに体系的にまとめます。FFmpeg 連携時に一緒に現れがちな CoreMedia/CoreVideo・libbz2 依存の対処も一気通貫で解説します。

ITtripTOOLS
その「面倒」、無料で解決。 ITtripがつくる、6つの道具。 無料ツール一覧へ すべて無料・追加課金なし
先頭0を守るCSV編集こわさないCSV PDFに直接書き込みかけるPDF 写真＋説明をPDFに写レポ スマホ⇄PCで共有コピペ便 · 文章・写真 みんなの日程を調整日程Fit 匿名質問・投票を集めるKOEQ
目次

症状

Undefined symbols for architecture arm64:
  "_AudioServicesCreateSystemSoundID", referenced from ...
  "_AudioServicesPlaySystemSound", referenced from ...
ld: symbol(s) not found for architecture arm64
clang: error: linker command failed with exit code 1 (use -v to see invocation)

<NativeReference> の <Frameworks>VideoToolbox,AudioToolbox</Frameworks> を宣言しているにも関わらず、最終リンクで AudioToolbox の解決に失敗します。シミュレータ（iossimulator-x64）では通るのに実機（ios-arm64）で落ちる、Release だけ落ちる、といった揺れ方をすることもあります。

原因の本質

  • 静的ライブラリは自己完結ではない：libmylib.a が C の関数（AudioToolbox の C API など）に依存しても、その依存フレームワークを自動では引っ張ってきません。最終リンク段階で -framework AudioToolbox を明示する必要があります。
  • MAUI（mtouch）の最終リンクは「2段構え」：MSBuild の <Frameworks> は中間生成物（Xcode プロジェクト相当）に伝わりますが、最後に mtouch が行うリンクに必ずしも伝播しないことがあります。ここで <MtouchExtraArgs> による直接指定が保険になります。
  • デッドストリップ／スマートリンク：ld は参照が弱い（または間接参照の）シンボルを掃除します。<ForceLoad> と <SmartLink>false はこの最適化を抑止し、静的ライブラリ内の必要オブジェクトを確実に取り込ませるためのカギです。

結論（最短ルートの設定）

次の2点で解決します。

  1. mtouch に -framework AudioToolbox を直渡し
  2. <NativeReference> でも重ねて宣言＋最適化抑止

1) MtouchExtraArgs に AudioToolbox を強制指定

&lt;PropertyGroup&gt;
  &lt;MtouchExtraArgs&gt;
    --cxx -gcc_flags "-framework AudioToolbox"
  &lt;/MtouchExtraArgs&gt;
&lt;/PropertyGroup&gt;
  • --cxx：静的ライブラリ側が C++ を含む場合の保険（libc++ 連携）。
  • -gcc_flags：最終リンクへそのまま渡されます（名前は歴史的経緯）。

ビルド構成を限定したい場合は条件付きにできます：

&lt;PropertyGroup Condition="'$(TargetFramework)'=='net8.0-ios' and '$(RuntimeIdentifier)'=='ios-arm64'"&gt;
  &lt;MtouchExtraArgs&gt;--cxx -gcc_flags "-framework AudioToolbox"&lt;/MtouchExtraArgs&gt;
&lt;/PropertyGroup&gt;

2) NativeReference を堅牢化

&lt;ItemGroup&gt;
  &lt;NativeReference Include="Platforms\iOS\lib\libmylib.a"&gt;
    &lt;Kind&gt;Static&lt;/Kind&gt;
    &lt;Frameworks&gt;VideoToolbox,AudioToolbox&lt;/Frameworks&gt;
    &lt;ForceLoad&gt;true&lt;/ForceLoad&gt;
    &lt;SmartLink&gt;false&lt;/SmartLink&gt;
  &lt;/NativeReference&gt;
&lt;/ItemGroup&gt;
  • ForceLoad：libmylib.a 全体の取り込みを保証。
  • SmartLink=false：デッドストリップの影響で必要コードが落ちるのを防止。
  • 同じフレームワークを <Frameworks> と <MtouchExtraArgs> に重複指定しても害はありません。伝播漏れ対策の二重化と考えてください。

FFmpeg 連携で「芋づる」発生する未定義シンボル

FFmpeg の静的ライブラリ群（libavcodec.a、libavformat.a など）を追加すると、AudioToolbox 以外にも依存が噴き出します。代表例と対処を表にまとめます。

未定義シンボル原因対応策
BZ2_bzDecompress* などFFmpeg を bzip2 (libbz2) 有効でビルドしている① FFmpeg を --disable-bzlib で再ビルドし依存を除去
② もしくは iOS 向けにビルドした libbz2.a を追加しリンク
_CMSampleBufferCreate ほかCoreMedia.framework が不足<Frameworks> または -framework CoreMedia を追加
_CVPixelBuffer* ほかCoreVideo.framework が不足<Frameworks> または -framework CoreVideo を追加

最終的に動作した設定例

&lt;PropertyGroup&gt;
  &lt;MtouchExtraArgs&gt;
    --cxx -gcc_flags "-framework AudioToolbox -framework CoreMedia -framework CoreVideo"
  &lt;/MtouchExtraArgs&gt;
&lt;/PropertyGroup&gt;

<ItemGroup>
<!-- 自前ライブラリ -->
<NativeReference Include="Platforms\iOS\lib\libmylib.a">
<Kind>Static</Kind>
<Frameworks>AudioToolbox,CoreMedia,CoreVideo,VideoToolbox</Frameworks>
<ForceLoad>true</ForceLoad>
<SmartLink>false</SmartLink>
</NativeReference>

<!-- FFmpeg ライブラリ群 -->
<NativeReference Include="Platforms\iOS\lib\libavcodec.a">
<Kind>Static</Kind>
<Frameworks>CoreMedia,CoreVideo,VideoToolbox</Frameworks>
<ForceLoad>true</ForceLoad>
<SmartLink>false</SmartLink>
</NativeReference>
<NativeReference Include="Platforms\iOS\lib\libavformat.a">
<Kind>Static</Kind>
<ForceLoad>true</ForceLoad>
<SmartLink>false</SmartLink>
</NativeReference>
<NativeReference Include="Platforms\iOS\lib\libavutil.a">
<Kind>Static</Kind>
<ForceLoad>true</ForceLoad>
<SmartLink>false</SmartLink>
</NativeReference>
<NativeReference Include="Platforms\iOS\lib\libswresample.a">
<Kind>Static</Kind>
<ForceLoad>true</ForceLoad>
<SmartLink>false</SmartLink>
</NativeReference>
<NativeReference Include="Platforms\iOS\lib\libswscale.a">
<Kind>Static</Kind>
<ForceLoad>true</ForceLoad>
<SmartLink>false</SmartLink>
</NativeReference>

<!-- bzip2 を使う場合のみ -->
<NativeReference Include="Platforms\iOS\lib\libbz2.a">
<Kind>Static</Kind>
<ForceLoad>true</ForceLoad>
<SmartLink>false</SmartLink>
</NativeReference>
</ItemGroup> </code></pre>

<h2>なぜ「&lt;Frameworks&gt;だけ」ではダメだったのか</h2>
<p><code>&lt;Frameworks&gt;</code> は MSBuild パイプラインの途中で生成されるバンドル情報に寄与しますが、最終的な <strong>mtouch のリンク行</strong>はプロジェクトの他設定や依存関係の解析結果次第で最適化・調整されます。ここで参照が弱い（または条件付き）なシンボルは取りこぼされる可能性があるため、<em>必ず</em> <code>&lt;MtouchExtraArgs&gt;</code> で <code>-framework</code> を直渡しするのが安全策です。二重化は冗長ではなく、<strong>最終段リンクへの伝播保証</strong>と理解してください。</p>

<h2>再発防止のためのチェックリスト</h2>
<ol>
  <li><strong>ネイティブ依存の棚卸し</strong>：<br><code>nm -gU libXXX.a | grep _</code> で「<em>未解決（U）シンボル</em>」を洗い出す。FFmpeg など複数の .a を束ねる場合はすべてに対して実施。</li>
  <li><strong><code>&lt;Frameworks&gt;</code> と <code>MtouchExtraArgs</code> を双方設定</strong>：<br>同じフレームワークを二重に書いても問題なし。むしろ安心。</li>
  <li><strong>外部圧縮／暗号ライブラリの有無</strong>：<br><code>zlib</code>／<code>bzlib</code>／<code>iconv</code>／<code>zstd</code> 等、FFmpeg のビルドオプションで依存が変わる。不要なら無効化、有用なら iOS 用に静的ビルドして追加。</li>
  <li><strong><code>ForceLoad=true</code> ＆ <code>SmartLink=false</code> を基本に</strong>：<br>カテゴリやコールバックベースの参照は検出が弱く、最適化で落ちがち。まずはこの組み合わせでビルドを安定化。</li>
  <li><strong>アーキテクチャの整合</strong>：<br><code>lipo -info libmylib.a</code> で <code>arm64</code> を含むことを必ず確認。シミュレータ用（<code>x86_64</code>／<code>arm64e</code>）しか入っていない「薄い」ライブラリは実機ビルドに失敗します。</li>
  <li><strong>C++ 混在の明示</strong>：<br>少しでも C++ コードが含まれるなら <code>--cxx</code> を付与。必要に応じて <code>&lt;IsCxx&gt;true&lt;/IsCxx&gt;</code> を <code>&lt;NativeReference&gt;</code> に追加すると確実です。</li>
  <li><strong>クリーンビルドで検証</strong>：<br>キャッシュに引っ張られないよう <code>bin/</code>・<code>obj/</code> を削除してから再ビルド。</li>
</ol>

<h2>トラブルシューティング（実践コマンド集）</h2>
<ul>
  <li><strong>未定義シンボルを探す</strong><br>
    <pre><code>nm -u path/to/libmylib.a | sort | uniq
nm -gU path/to/libavcodec.a | grep -E "AudioServices|CMSampleBuffer|CVPixelBuffer|BZ2"

アーキテクチャを確認

lipo -info path/to/libmylib.a

静的ライブラリの中身（オブジェクトファイル）を確認

ar -t path/to/libmylib.a | head

最終リンク行を詳しく見る

dotnet build -f net8.0-ios -c Release -v:n
# あるいは -v:detailed で、mtouch が実行する ld の引数を観察

FFmpeg 側のビルド方針（依存を最小化する）

iOS への静的リンクは「依存が少ないほど勝ち」です。以下は実運用で安定している構成の考え方です。

  • 不要機能は無効化：--disable-bzlib、--disable-iconv、--disable-autodetect などで依存を削る。
  • ハードウェアアクセラレーション：VideoToolbox を使うなら --enable-videotoolbox。その場合は CoreMedia/CoreVideo の追加も忘れずに。
  • ビルド成果物の粒度：使わないライブラリ（swscale など）はそもそもリンクしない。1つでも余計な .a があると依存が発火しやすい。

「ビルドは通るが実機で動かない」を潰す最終点検

  1. Entitlements／Info.plist の権限：AudioToolbox のシステム音は一般に追加権限不要ですが、マイク入出力や背景音再生を同時に扱う場合は NSMicrophoneUsageDescription のようなキーが要るシナリオもあります。
  2. RuntimeIdentifier を明示：CI/CD での取り違え防止に <RuntimeIdentifier>ios-arm64</RuntimeIdentifier> を設定しておくと確実。
  3. Release/Debug で同じフラグか：Release でのみ最適化が強く、SmartLink の影響が変わることがあるため、両構成で MtouchExtraArgs を揃える。

よくある誤解と解毒

誤解正しい理解
「<Frameworks> に書けば十分」最終リンクまでは保証されないことがある。-framework を MtouchExtraArgs で直渡しする。
「ForceLoad は重くなるから使わない」ビルドサイズ・リンク時間の増加は限定的。未定義で止まる方が痛い。問題切り分け中は常時有効に。
「AudioToolbox は iOS 標準だから自動でリンクされる」自動では来ない。依存は依存として明示するのが鉄則。
「シミュレータで動くなら実機も動く」アーキテクチャや最適化が異なる。実機（arm64）で必ず検証する。

設計メモ：AudioToolbox を呼ぶ側のベストプラクティス

  • API は C 層で薄く包む：MAUI からは P/Invoke で最小限の関数に橋渡し。Swift/Objective‑C のカテゴリ拡張に頼らない構造にするとリンクが安定します。
  • 戻り値とエラーの伝搬：AudioServices 系は OS 側で失敗しても戻り値でしかわかりません。成功／失敗を OSStatus で受け取り、.NET 例外にマッピングしておくと保守性が高まります。
  • サウンドIDのライフサイクル：AudioServicesCreateSystemSoundID → 再生 → AudioServicesDisposeSystemSoundID を必ず対で。リークすると実機で症状が出やすい。

終端まとめ（現場の手順書）

  1. まず 未定義シンボルの一覧を nm で出す。
  2. 足りない Apple フレームワークを <Frameworks> と MtouchExtraArgs の両方に列挙（AudioToolbox／CoreMedia／CoreVideo）。
  3. 静的ライブラリは ForceLoad=true・SmartLink=false で登録。
  4. FFmpeg 由来の bzip2 依存は、--disable-bzlib で消すか、libbz2.a をリンク。
  5. アーキテクチャ（arm64）と C++ 有無（--cxx）を確認。
  6. クリーンビルド → 実機で動作確認。

テンプレ：問題解決に使い回せる .csproj 断片

<PropertyGroup Condition="'$(TargetFramework)'=='net8.0-ios'">
  <RuntimeIdentifier>ios-arm64</RuntimeIdentifier>
  <MtouchExtraArgs>
    --cxx -gcc_flags "-framework AudioToolbox -framework CoreMedia -framework CoreVideo"
  </MtouchExtraArgs>
</PropertyGroup>



Static
true
AudioToolbox,CoreMedia,CoreVideo,VideoToolbox
true
false




Static
true
false




Static
true
false

チェックリスト（配布前の最終確認用・印刷推奨）

項目観点確認方法
フレームワーク指定AudioToolbox/ CoreMedia / CoreVideo を二重化.csproj の <Frameworks> と <MtouchExtraArgs>
スマートリンク抑止必要コードのデッドストリップ防止ForceLoad=true、SmartLink=false
FFmpeg 依存bzlib など外部依存の最小化FFmpeg の configure オプション確認
アーキテクチャarm64 を含むlipo -info
C++ 有無--cxx 指定の整合MtouchExtraArgs または <IsCxx>
未定義の有無未知の「U」シンボルが残っていないnm -u の結果ゼロ
実機試験通知音・再生・解放の動作サウンド ID のライフサイクル確認

まとめ

AudioToolbox の未定義シンボルは、最終リンクへ -framework を直渡しし、ForceLoad と SmartLink=false で最適化を抑えることで解消します。FFmpeg を同梱するなら、CoreMedia/CoreVideo と外部圧縮ライブラリ（とくに libbz2）の取り扱いが定石です。MAUI の iOS ネイティブ連携は「依存を明示する」「最終リンクを制御する」の二本柱。ここさえ押さえれば、AudioToolbox、FFmpeg + VideoToolbox を含む構成でも安定してビルド・動作させられます。

付録：簡易デバッグ・スクリプト（任意）

プロジェクトの Platforms/iOS/lib 直下を検査するワンライナー例です。CI の前段で差し込み、早期に依存漏れを検出できます。

#!/usr/bin/env bash
set -euo pipefail
LIBDIR="Platforms/iOS/lib"
echo "[arm64 check]"
for a in "$LIBDIR"/*.a; do
  echo -n "$(basename "$a"): "
  lipo -info "$a" | sed 's/.*are: //'
done

echo "[undefined symbols of interest]"
for a in "$LIBDIR"/*.a; do
nm -gU "$a" | grep -E "U _AudioServices|U _CMSampleBuffer|U _CVPixelBuffer|U *BZ2*" || true
done

付録：P/Invoke 最小例（AudioToolbox）

ネイティブ側の API を薄く包み、.NET では責務を厳格化して扱います。

// C レイヤ（libmylib.a 側）
#include <AudioToolbox/AudioToolbox.h>

OSStatus PlaySystemSoundFromURL(CFURLRef url) {
SystemSoundID sid = 0;
OSStatus st = AudioServicesCreateSystemSoundID(url, &sid);
if (st != noErr) return st;
AudioServicesPlaySystemSound(sid);
AudioServicesDisposeSystemSoundID(sid);
return noErr;
} 
// C# 側（.NET MAUI）
using System;
using System.Runtime.InteropServices;

static class NativeAudio
{
    [DllImport("__Internal")]
    private static extern int PlaySystemSoundFromURL(IntPtr cfUrl);

    public static void PlayFromFile(string path)
    {
        if (string.IsNullOrEmpty(path)) throw new ArgumentNullException(nameof(path));
        using var url = CF.CFUrlCreateFromFile(path); // 自作の CFURL ラッパー想定
        var status = PlaySystemSoundFromURL(url.Handle);
        if (status != 0) throw new InvalidOperationException($"AudioToolbox error: {status}");
    }
}

この形なら、リンクのために必要なシンボルが はっきり 参照され、ForceLoad との相性も良くなります。

付録：ビルドログを読む（何が渡っているか？）

-v:detailed でビルドすると、mtouch が最終的に実行したリンカ行が表示されます。そこに -framework AudioToolbox、-framework CoreMedia、-framework CoreVideo が並んでいるかを目視で確かめましょう。もし欠けているなら、MtouchExtraArgs の引用符（ダブルクォート）やスペース区切りを見直してください（よくあるのは全角スペース混入や改行位置のズレ）。

クロージング

ネイティブ連携での「未定義シンボル」は、設定と観察の手順を一度整備してしまえば、以後は 機械的に再現・解決できます。本稿のテンプレとチェックリストをチームの標準に組み込み、AudioToolbox／FFmpeg／VideoToolbox のような複合依存でも、迷わず安定した .NET MAUI iOS アプリを届けていきましょう。

C#
.NET MAUI 静的ライブラリ iOS FFmpeg AudioToolbox リンクエラー

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次