更新履歴
2017/04/25 Ver.1.0.0.1 リリース版
2017/04/26 Ver.1.1.0.0 C-FA 1.10対応

1. 概要

1.1 C-FAについて

C-FAは、アクセルが開発したサウンドコーデック・ミドルウェアです。C-FAはマルチプラットフォームでの再生に対応しており、Windows、Mac、Android、iOSでのデコードが可能です。汎用音声コーデックの音質を目指し、さらに、より低負荷での再生を実現するために開発されました。また、シークポイントの設定やなめらかなループ再生、高精度の位置情報取得に対応しています。

1.2 C-FA SDKについて

C-FA SDKは、C-FAを使用したアプリケーションを開発するための開発ツールとライブラリのソフトウェアスイートです。C-FA SDKには以下が含まれます。

項目 概要 フォルダ名 ファイル名

オーサリング用ツール

音声ファイルから.cfaファイルを生成するためのエンコードツールと、.cfaファイルから.wavファイルを生成するためのデコードツールが含まれます。Windows版とMac版が含まれます。

tools/mac
tools/x86

cfaenc_c

cfadec_c

プレイヤツール

.cfaファイルを再生するためのプレイヤアプリケーションです。Windows版とMac版が含まれます。

tools/mac
tools/x86

amplay

デコードライブラリ

各プラットフォームで.cfaファイルをデコードするためのライブラリが含まれます。

library

*.a

*.so

*.dll

*.dylib

JNI プラグイン

Android SDKでcfaファイルをデコードするためのプラグインが含まれます。

jni

*.java

*.so

Unityプラグイン

Unityで.cfaファイルをデコードするためのプラグインが含まれます。

unity

*.a

*.so

*.dll

*.bundle

*.cs

依存ライブラリ

Windowsで必要なOpenALのインストーラが含まれます。

thirdparty

oalinst.exe

サンプルプログラム

.cfaファイルからデコードと再生を行うサンプルが含まれます。

sample

*.cpp

*.java

1.3 対応プラットフォーム

OS バージョン デコードライブラリ名

Windows

Windows7 以降

cfadec.dll

cfaplay.dll

Mac

Mac OS X 10.7以降

cfadec.dylib

cfaplay.dylib

cfadecplay.bundle

Android

Android OS 4.0以降

libcfadec-VER.a(*)

libcfaplay-VER.a(*)

libcfadecplay.so(*)

iOS

iOS 6.0以降

cfadec-VER.a(*)

cfaplay-VER.a(*)

1.4 依存ライブラリ

C-FAのPlayerAPIでは、Windows、Mac、iOSでOpenALを、AndroidでOpenSLを使用しています。WindowsでPlayerAPIを使用する場合、OpenALをインストールする必要があります。thirdpartyフォルダのoainst.exeを実行してインストールして下さい。Mac、iOS、Androidでは標準でライブラリがインストールされています。

2. オーサリング

2.1 エンコード設定

エンコーダで設定できる項目を以下に示します。

オプション 機能

--input , -i

入力ファイルを指定します。

WAVEファイル(.wav)を指定して下さい。

--output , -o

出力ファイルを指定します。

拡張子はcfa(.cfa)に指定して下さい。

--quality , -q

音質を1~21で指定します。

大きいほど高音質です。デフォルト値は5です。

--seekpoint , -s

シークポイントをサンプル単位で指定します。

シークポイントを設定した位置へのシークは高速になります。

--autoloop , -a

ループ位置をサンプル単位で指定します。

指定したループ位置はデコードライブラリで取得することができます。

なお、Player APIを利用した際は自動的にループします。

2.2 エンコードの例

cfaenc_cを使用してcfaファイルを生成する例です。

コマンド例 解説

cfaenc_c -q 5 –i in.wav –o out.cfa

クオリティ値5 でin.wavをout.cfaに変換します。

cfaenc_c –s 10000 –i in.wav -o out.cfa

サンプル位置10000にシークポイントを設定して変換します。

2.3 デコード設定

デコーダで設定できる項目を以下に示します。

オプション 機能

--input , -i

入力ファイルを指定します。

CFAファイルを指定して下さい。

--output , -o

出力ファイルを指定します。

拡張子はwavにして下さい。

2.4 デコードの例

cfadec_cを使用してwavファイルを生成する例です。

コマンド例 解説

cfadec_c –i in.cfa –o out.wav

in.cfaをout.wavに変換します。

2.5 プレイヤーでの再生

.cfaファイルをamplayに関連付けることで再生可能です。

2.6 ビットレート

クオリティ値に対応する概算ビットレートは以下となります。なお、クオリティに対するビットレートは素材の特性により変動します。

クオリティ値 サンプルビット数 モノラル(kbps) ステレオ(kbps) 補足
1 1.0 43 86
2 1.25 53 107
3 1.50 64 129
4 1.75 75 150
5 2.00 86 172 C-FA デフォルト値
6 2.25 96 193
7 2.50 107 215
8 2.75 118 236
9 3.00 129 258
10 3.25 139 279
11 3.50 150 301
12 3.75 161 322
13 4.00 172 344
14 4.25 183 366
15 4.50 193 387
16 4.75 204 409
17 5.00 215 430
18 5.25 226 452
19 5.50 236 473
20 5.75 247 495
21 6.00 258 516

3. ライブラリのリンク

3.1 インタフェース定義のinclude

headerフォルダにあるcfadec.hおよびcfaplay.hをincludeします。

3.2 ライブラリのWindowsプロジェクトへのインポート

windowsフォルダにあるcfadec.libおよびcfaplay.libをアプリケーションにリンクします。windows/x86-x64フォルダにあるcfadec.dllをアプリケーションと同じフォルダに置きます。

3.3 ライブラリのMacプロジェクトへのインポート

macフォルダにあるcfadec.dylibをアプリケーションにリンクします。cfadec.dylibをパスの通った場所に配置します。

3.4 ライブラリのiOSプロジェクトへのインポート

Xcodeのバージョンに応じて、以下のいずれかのライブラリをXcodeにドロップします。

Xcode ライブラリ C++ Standard Library Enable Bitcode

7 , 8

ios/cfadec-VER-xc7.a

ios/cfaplay-VER-xc7.a

libc++

対応

尚、Player APIを使用する場合は、OpenALをLinked Frameworks and Librariesに登録する必要があります。cfaファイルはXcodeのSupportingFilesに登録します。

3.5 ライブラリのAndroid NDKプロジェクトへのインポート

Androidフォルダにあるcfadec-VER.aおよびcfaplay-VER.aをアプリケーションにリンクします。

各ライブラリのビルド設定は以下になります。

ライブラリ APP_PLATFORM APP_STL APP_CPPFLAGS

android/libcfadec-VER.a

android-9

gnustl_static

-std=c++11

android/libcfaplay-VER.a

android-9

gnustl_static

-std=c++11

Application.mkには以下のような記述を行って下さい。

APP_OPTIM := release
APP_ABI := armeabi-v7a
APP_PLATFORM := android-10
APP_STL := gnustl_static

Android.mkには以下のような記述を行って下さい。

LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
ARMEABI := armeabi-v7a

LOCAL_MODULE    := libcfadec-st
LOCAL_SRC_FILES := ../../static_lib_dec/obj/local/$(ARMEABI)/libcfadec.a
include $(PREBUILT_STATIC_LIBRARY)

LOCAL_MODULE    := libcfaplay-st
LOCAL_SRC_FILES := ../../static_lib_play/obj/local/$(ARMEABI)/libcfaplay.a
include $(PREBUILT_STATIC_LIBRARY)

include $(CLEAR_VARS)

LOCAL_CFLAGS += -DANDROID -DNDEBUG
LOCAL_CPPFLAGS += -I ../../../../export -fvisibility=hidden

LOCAL_CPPFLAGS += -fexceptions
LOCAL_MODULE    := libcfadecplay

LOCAL_ARM_MODE	:= arm
LOCAL_ARM_MODE	:= thumb

LOCAL_SRC_FILES	+= jni.cpp main.cpp

LOCAL_LDLIBS            :=  -lm -lz -llog -ldl -lOpenSLES

LOCAL_STATIC_LIBRARIES  := cpufeatures libcfadec-st libcfaplay-st

include $(BUILD_SHARED_LIBRARY)

$(call import-module,cpufeatures)

4. Decoder API

4.1 Decoder APIとは

Decoder APIでは、cfaファイルからPCMを取得することができます。

4.2 インタフェース定義

インタフェース仕様はcfadec.hに記載されています。

4.3 デコードサンプル

次の例では、iOSリソースのsample.cfaから音声をデコードします。

#include "cfadec.h"
NSString *path=[[NSBundle mainBundle] pathForResource:@"sample" ofType:@"cfa"];

struct CFADecoder *dec;
int ret=cfadCreate(&dec);
if(ret!= CFADEC_STATUS_SUCCESS) { //エラー }

ret=cfadOpenStreamFile(dec,[path cStringUsingEncoding:1]);
if(ret!= CFADEC_STATUS_SUCCESS) { //エラー }

cfadStreamInfo info;
ret=cfadGetStreamInfo(dec,&info,RM5DEC_MOVIE_INFO_VERSION);
if(ret!= CFADEC_STATUS_SUCCESS) { //エラー }

std::vector pcm(info.samples*info.channels);

int ret=cfadDecode(dec,&pcm[0],pcm.size()*sizeof(short),0,info.samples);
if(ret!= CFADEC_STATUS_SUCCESS) { //エラー }

cfadDestroy(dec);

4.4 サンプルプログラム

Decoder APIのサンプルプログラムは sample/decoder.cpp を参照して下さい。

5. Player API

5.1 Player APIとは

Player APIでは、cfaファイルから直接再生することができます。
Androidの場合はOpenSLが、それ以外ではOpenALが使用されます。

5.2 インタフェース定義

インタフェース仕様はcfaplay.hに記載されています。

5.3 再生の例

次の例では、iOSリソースのsample.cfaから音声を再生します。

#include "cfaplay.h"
ret=cfapInitialize(CFAPLAY_BUFFER_SIZE_DEFAULT);
if(ret!= CFAPLAY_STATUS_SUCCESS) { //エラー }

NSString *path=[[NSBundle mainBundle] pathForResource:@"sample" ofType:@"cfa"];

struct CFAPlayer *player;
int ret=cfapCreate(&player);
if(ret!= CFAPLAY_STATUS_SUCCESS) { //エラー }

ret=cfapOpenStreamFile(player,[path cStringUsingEncoding:1]);
if(ret!= CFAPLAY_STATUS_SUCCESS) { //エラー }

int ret=cfapPlay(player);
if(ret!= CFAPLAY_STATUS_SUCCESS) { //エラー }

cfapDestroy(player);

cfapUninitialize();

5.4 サンプルプログラム

Player APIのサンプルプログラムは sample/player.cpp を参照して下さい。

6. JNI Plugin

6.1 JNI Pluginの概要

JNI Pluginは、C-FAをJAVAプログラムから呼び出すためのAndroid SDK向けプラグインです。C-FAのネイティブライブラリと、インタフェース定義JAVAファイルから構成されます。

6.2 プロジェクトへのインポート

jniフォルダのlibs/*とsrc/axell/*をAndroid SDKプロジェクトにインポートして下さい。

6.3 音声ファイルのインポート

エンコードした.cfaファイルをプロジェクトのres/rawにインポートして下さい。

6.4 再生の例

APIの仕様は src/axel/cfa/CFAPlayer.java に記載しています。
次の例では、SDカードに格納したtest.cfaを再生します。

CFAPlayer.cfapInitialize(BUFFER_SIZE);
m_instance_audio=CFAPlayer.cfapCreate("/sdcard/test.cfa");
CFAPlayer.cfapPlay(m_instance_audio);
try {
Thread.sleep(10000);
} catch (InterruptedException e) {
}
CFAPlayer.cfapDestroy(m_instance_audio);
CFAPlayer.cfapUninitialize();

6.5 サンプルプログラム

jni/src/user/cfaplaysample/CFAPlaySampleActivity.java にC-FAで音声を再生するサンプルプログラムが含まれています。

7. Unity Plugin

7.1 Unity Pluginの概要

Unity Pluginは、C-FAをUnityから呼び出すためのプラグインです。C-FAのネイティブライブラリと、インタフェース定義C#ファイルから構成されます。具体的に、CFADecoder.csおよびCFAPlayer.csに定義されたインタフェースから、ネイティブライブラリのC++ APIを呼び出します。
また、Unityから簡単に音を鳴らすためのCFAAudioクラスも付属します。CFAAudioクラスでは、CFAPlayerクラスを使用して、StreamingAssetsフォルダの.cfaファイルを簡単な操作で再生することができます。
Unity Pluginは、Windows、Mac、Android、iOSに対応します。

C-FA Unity Pluginの概要

7.2 プラグインのUnityプロジェクトへのインポート

unity/Assetsフォルダを、任意のUnityプロジェクトのAssetsフォルダにコピーして下さい。再生したいcfaファイルをStreamingAssetsフォルダにコピーして下さい。

7.3 Decoder API、Player API

Unity Pluginでは、C++ APIと共通のAPIが定義されています。APIの使用方法は、C++ APIの項目を参照して下さい。

7.4 Audio API

Audio APIはUnity向けの高レベルな再生APIです。APIの一覧を以下に示します。

初期化API
API 引数 返値 説明

Initialize()

-

成功時はtrue、失敗時はfalse

デバイスを初期化します。最初のファイルの再生を開始する前に、一度だけ呼び出す必要があります。

Uninitialize()

-

-

デバイスを解放します。全てのファイルの再生が終了してから呼び出す必要があります。

再生制御API
API 引数 返値 説明

Open(file_name)

file_name : string

成功時はtrue、失敗時はfalse

cfaファイルを開きます。

Open(buf)

buf : byte[]

成功時はtrue、失敗時はfalse

cfaファイルをメモリから開きます。

OpenOrAdd(file_name,offset,handle)

file_name : string

offset : int

handle : int

成功時はtrue、失敗時はfalse

cfaファイルを開くもしくは追加します。同時に再生遅延の設定および追加したcfaファイルのハンドルを得ます。

OpenOrAdd(buf,offset,handle)

buf : byte[]

offset : int

handle : int

成功時はtrue、失敗時はfalse

cfaファイルを開くもしくは追加します。同時に再生遅延の設定および追加したcfaファイルのハンドルを得ます。

Play()

-

成功時はtrue、失敗時はfalse

音声を再生します。再生に失敗した場合はfalseを返します。

Stop()

-

-

再生を停止します。

Seek(sample)

sample : uint

成功時はtrue、失敗時はfalse

指定したサンプル番号にシークします。

再生設定API
API 引数 返値 説明

Loop(sample)

sample : float

成功時はtrue、失敗時はfalse

ループ再生時のサンプル数を指定します。-1を指定するとループしません。デフォルト値は-1です。

Pitch(pitch)

pitch : float

成功時はtrue、失敗時はfalse

再生速度を変更します。有効範囲は0.5~2.0です。

Volume(vol)

vol : float

成功時はtrue、失敗時はfalse

再生速度を変更します。有効範囲は0〜1です。

Panning(pan)

pan : float

成功時はtrue、失敗時はfalse

定位を変更します。有効範囲は-1〜1です。

LowPass(khz)

khz : float

成功時はtrue、失敗時はfalse

ローパスフィルタを設定します。有効範囲は0.02~20です。20より大きな値を設定するとフィルタリングが行われません。

HighPass(khz)

khz : float

成功時はtrue、失敗時はfalse

ハイパスフィルタを設定します。有効範囲は0.02~20です。20より大きな値を設定するとフィルタリングが行われません。

情報取得API
API 引数 返値 説明

CurrentPosition()

-

float

音声の再生位置を秒数で返します。

Playing()

-

再生中はtrue,再生していない場合はfalse

再生しているかどうかを取得します

Pausing()

-

一時停止中はtrue,一時停止していない場合はfalse

一時停止しているかどうかを取得します。

Info()

-

成功時はストリーム情報構造体、失敗時はnull

開いているストリームの情報をcfapStreamInfo構造体で返します。

Error()

-

エラーコード

再生中にエラーが発生した場合はCFAPLAY_STATUS_SUCCESS以外のエラーコードを返します。

7.5 ストリーム情報構造体

Info APIで取得できる情報の一覧です

cfaStreamInfo 構造体
メンバ 説明
stream_size ストリームサイズ(バイト単位)
channels チャンネル数
samples チャンネル単位のサンプル数
sampling_rate サンプリング周波数
frames フレーム数
quality エンコード時に設定したクオリティ値
autoloop 自動ループ設定
max_seekpoint_no 使用しているシークポインごとの番号の最大(0〜CFADEC_SEEKPOINT_MAX-1)
stream_type ストリームタイプ CFADEC_STREAM_TYPE_*

7.6 デコードサンプル

次の例では、StreamingAssetsフォルダに置いたbgm.cfaを再生します。

private CFAAudio audio;

public Start(){
  CFAAudio.Initialize()
  audio=new CFAAudio();
  audio.Open(Application.streamingAssetsPath+"/bgm.cfa");
  audio.Play();
}
public OnApplicationQuit(){
  audio.Stop();
  CFAAudio.Uninitialize();
}

7.7 制約事項

Unity の Audio API との競合を避けるため、Edit -> Project Settings -> Audio から AudioManager を開き、Inspector内のDisable Audio にチェックを入れて下さい。また、Camera に付加されている AudioListener のチェックを外して下さい。Unity のスレッドの解放との競合を避けるため、CFAAudio.Uninitialize は OnApplicationQuit で呼び出して下さい。

7.8 Androidにおけるバックグラウンド処理

Android の場合、アプリケーションがバックグラウンドに移った場合も再生が停止しません。そのため、以下のように、OnApplicationPause で一時停止を行う必要があります。


void OnApplicationPause (bool pauseStatus)
{
  if (pauseStatus){
    for(int i=0; i < CFA_AUDIO_MAX; i++ ){
      if(cfa[i] != null && cfa[i].Playing()){
        cfa[i].Pause();
      }
    }
  } else {
    for(int i=0; i < CFA_AUDIO_MAX; i++ ){
      if(cfa[i] != null && cfa[i].Pausing()){
        cfa[i].Play();
      }
    }
  }
}
          

7.9 サンプルプログラム

Assets/CFASample.csを任意のゲームオブジェクトにアタッチして下さい。
自動的に、Assets/StreamingAssets/*.cfaが再生されます。
サンプルプログラムではAndroidを考慮し、WWWクラス経由でcfaファイルを再生します。
Windows、Mac、iOSではFile APIを使用することも可能です。