CRI ADX2(AtomCraft)
ロボット編06　プロジェクトの作成と波形ファイルをキューに登録

スクリプトファイルの準備

スクリプトメニューで「スクリプトリスト...」を選択し、スクリプトリストからのスクリプト実行ウィンドウ表示します。
スクリプトリストウィンドウの新規作成ボタンを押して、以下の名前でスクリプトファイルを作成します。

スクリプトの説明

作成したスクリプトをダブルクリックして、スクリプトエディターからのスクリプト実行で開きます。
スクリプトリストからのスクリプト実行ウィンドウでスクリプトの内容が一覧できるように、スクリプトの説明を次のように記述しましょう。

# --Description:[チュートリアル]プロジェクト〜キューまでの基本再生データ作成と保存

モジュールのインポート

スクリプトの説明が記述できたら、スクリプトでCRI Atom Craftを操作するため、モジュールをインポートします。
スクリプトエディターからのスクリプト実行で、以下のインポート処理を書いてみましょう。

import sys
import os
import cri.atomcraft.debug as acdebug
import cri.atomcraft.project as acproject

今回は、Pythonの標準モジュールsys、osの他、CRI Atom Craftの操作モジュールを2つインポートしています。
チュートリアル「Hello Worldをスクリプトログに表示する」で使用したDebugモジュールに加え、CRI Atom Crafのプロジェクトデータを操作するProjectモジュールをインポートしています。

プロジェクト名、プロジェクト保存先の設定

次に、作成するプロジェクト名、プロジェクト保存先、チュートリアル用波形ファイルの場所を、以下の内容でスクリプトに書きます。

これらのプロジェクト情報をスクリプトで記述すると次のようになります。

# 作成するプロジェクト名
project_name = "Project_Tutorial"

# プロジェクトを作成する場所
projects_dir = os.path.expanduser('~/Documents/CRIWARE/CriAtomCraft/projects')
if not os.path.isdir(projects_dir):
    os.makedirs(projects_dir)

# チュートリアル用音声素材の場所
data_dir = os.path.dirname(os.path.dirname(__file__)) + '/tutorial_data'

os.path.expanduser 関数は、「~」をユーザーのホームディレクトリに展開してパスを作成する、PythonのOSモジュールの関数です。
「~」がユーザーのホームディレクトリに置きかわります。
os.path.isdir関数でディレクトリがあるか確認し、無ければos.makedirs関数で作成しています。

os.path.dirname 関数は、パスのが存在するディレクトリーを取得する関数です。
Pythonでは、__file__ に実行ファイルのパスが格納されています。
チュートリアルで使用する波形ファイルは、実行スクリプトファイルの２つ上のディレクトリーの「tutorial_data」フォルダーにあります。
os.path.dirnameを２回実行して、２つ上のディレクトリーを取得し、'tutorial_data'をチュートリアル用波形ファイルの場所に指定しています。

プロジェクト作成、ワークユニット作成

使用するモジュールのインポート設定、プロジェクト名、プロジェクト保存先の設定ができました。
ここからは、実際にCRI Atom Craftのデータ操作をしていきます。
モジュールのインポートでインポートした、Projectモジュールには、プロジェクト、ワークユニットを作成する次の関数が用意されています。

これらの関数を使って、プロジェクト、ワークユニットの作成をスクリプトで記述すると次のようになります。

# プロジェクト作成
result = acproject.create_project(projects_dir, project_name, True)
if not result["succeed"]:
    acdebug.warning("Failed Create Project")
    sys.exit()

# ワークユニット作成
result = acproject.create_workunit("WorkUnit_Tutorial", True, None)
if not result["succeed"]:
    acdebug.warning("Failed Create WorkUnit")
    sys.exit()

# ワークユニット情報を取得
workunit = result["data"]

スクリプトを記述して、一度、スクリプトを実行してみましょう。
スクリプトを実行すると、「Documents/CRIWARE/CriAtomCraft/projects」以下にワークユニット「WorkUnit_Tutorial」を含んだ「Project_Tutorial」プロジェクトが作成されます。

プロジェクト作成の解説

プロジェクトを作成するcreate_project関数には、「プロジェクト名」、「プロジェクト保存先」、「プロジェクトの上書きするか」の３つの情報を指定します。
3つ目の「プロジェクトの上書きするか」はTrueを指定すると、プロジェクト保存先に同名のプロジェクトファイルが存在しても、上書きして新たにプロジェクトを作成します。
関数を実行すると、実行結果が戻り値として返されます。ここでは返ってきた実行結果をresult変数に格納しています。

result変数には、関数実行結果の様々な情報が格納されており、識別文字（キー）を使って情報を取り出すことができます。
関数の実行が成功したか？は"succeed"キーで取得します。
result 変数に格納された"succeed"キーの情報を取得し、プロジェクト作成の成否を確認しています。
プロジェクトの作成に失敗した場合、ログ出力してスクリプトの実行を終了しています。

if 条件式:
    処理
    処理

ワークユニット作成の解説

ワークユニットを作成するcreate_workunit関数には、「ワークユニット名」、「マテリアルをワークユニットで管理するか」、「キュー作成時に設定するバスマップ」の情報を指定します。
create_workunit関数を実行すると、create_project関数と同様に実行結果が戻り値としてresult変数に格納されます。
result変数には、関数の実行成否の "succeed" キーの情報他、"data"　キーに作成したワークユニットを識別する情報が格納されています。

ワークユニットの作成が成功したか判定後、この後の処理でワークユニットの情報を使用するため、result["data"] にてワークユニット情報を取得し、workunit 変数に格納しています。

マテリアル登録

プロジェクト、ワークユニットの作成ができました。
作成したワークユニットのマテリアル情報に波形ファイルを登録してマテリアルを作成します。
次の関数を使って、マテリアルルートフォルダーに波形ファイルを登録します。

これらの関数を使って、マテリアルの登録をスクリプトで記述すると次のようになります。

# マテリアルルートフォルダー取得
material_root_folder = acproject.get_material_rootfolder(workunit)["data"]

# マテリアルルートフォルダに波形ファイルを登録
material = acproject.register_material(material_root_folder, data_dir+"/tutorial_data01/gun1_High.wav")["data"]

マテリアル登録の解説

マテリアルを登録するためのregister_material関数には、「登録先のフォルダー」、「登録する波形ファイル」の２つの情報を指定します。
このため、まずget_material_rootfolder関数を使って、ワークユニットのマテリアルルートフォルダーを取得しています。
次に、register_material関数を使って、マテリアルルートフォルダーに波形フィアルを登録し、マテリアルを作成しています。

ここまでのスクリプトを実行すると、ワークユニットのマテリアルルートフォルダーに "gun1_High.wav" マテリアルが作成されていることを確認することができます。

material_root_folder = acproject.get_material_rootfolder(workunit)["data"]

キューシート作成、キュー作成、ウェーブフォームリージョン作成

ワークユニットのマテリアル情報に波形ファイルの登録ができました。
次の関数を使って、キューシートを作成し、その中にキューを作成して、マテリアルをキューに登録してウェブフォームリージョンを作成します。

これらの関数を使って、キューシート、キューの作成とマテリアルの設定をスクリプトで記述すると次のようになります。

# ----- キューシート・キューの作成 -----
# キューシートフォルダを取得
cuesheet_rootfolder = acproject.get_cuesheet_rootfolder(workunit)["data"]

# キューシートフォルダ「WorkUnit_Tutorial」を取得
cuesheet_folder = acproject.get_child_object(cuesheet_rootfolder, "CueSheetFolder", "WorkUnit_Tutorial")["data"]

# キューシートフォルダにキューシートを作成
cuesheet = acproject.create_object(cuesheet_folder, "CueSheet", "Tutorial")["data"]

# ----- キュー・トラック・ウェーブフォームリージョンを作成 -----
# キューを作成
cue = acproject.create_object(cuesheet, "Cue", "gun1_High")["data"]
# トラックを作成
track = acproject.create_object(cue, "Track", "Track")["data"]
# マテリアルを指定してウェーブフォームリージョンを作成
waveform_region = acproject.create_waveform_region(track, material)["data"]

キューシート作成の解説

キューシート作成先のフォルダーを取得するために、get_cuesheet_rootfolder関数を使用してワークユニットのキューシート ルートフォルダーを取得します。
次に、get_child_object関数を使用して、キューシートルートフォルダー直下の"WorkUnit_Tutorial"フォルダーを取得します。
get_child_object関数には、「取得元のオブジェクト情報」、「取得するオブジェクトタイプ」、「取得するオブジェクトの名称」を指定します。

"WorkUnit_Tutorial"フォルダーはワークユニット作成時に自動的に作成される、ワークユニットと同名のフォルダーです。
このフォルダーにキューシート作成することで、ACB（ゲームデータ）の出力先をワークユニット単位で分離することができます。

取得した作成先のキューシートフォルダー、キューシートオブジェクトタイプ"CueSheet"、キュシート名"Tutorial"を指定して、汎用オブジェクト作成関数であるcreate_object関数でキューシートを作成しています。
create_object関数には、「作成元のオブジェクト情報」、「作成するオブジェクトのタイプ」、「作成するオブジェクトの名称」を指定します。

キュー・トラック・ウェーブフォームリージョン作成の解説

作成したキューシートにキュー、トラック、ウェーブフォームリージョンを順次作成します。
ウェーブフォームリージョンを作るのにキューとトラックが必要なの？と悩んでしまった人は「CRI Atom Craftのオブジェクト構造を理解しよう」にあるオブジェクト構造を見直してみるとよいでしょう。
キュー、トラック、ウェーブフォームリージョンが階層関係にあることが理解できるはずです。
キュー、トラックはキューシート同様、create_object関数を使用して作成しています。
ウェーブフォームリージョンは専用のcreate_waveform_region関数に、「作成先のトラック情報」「参照するマテリアル」を指定して作成しています。

cue = acproject.create_simple_cue(cuesheet, material)["data"]

プロジェクト保存

プロジェクトを作成して、波形ファイルを登録したキューの作成までができました。
最後に、作成したプロジェクトの保存を行い本チュートリアルを終了します。

プロジェクトの保存は、次の関数を使用します。

この関数を使って、プロジェクトの保存をスクリプトで記述すると次のようになります。

# プロジェクトの保存
result = acproject.save_project_all()

# 保存に失敗したときのために、結果を確認する。失敗していたらメッセージを出力する。
if not result["succeed"]:
    acdebug.warning("プロジェクトファイルの保存に失敗しました。")