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

このチュートリアルでは、プロジェクトの作成から、キューに波形ファイルを登録するまでの処理を実行するスクリプトを次の順序で書いていきます。

  • スクリプトファイルの準備
  • モジュールのインポート
  • プロジェクト名、プロジェクト保存先の設定
  • プロジェクト作成、ワークユニット作成
  • マテリアル登録
  • プロジェクト保存
オブジェクト作成の基本方法について習得しましょう。

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

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

スクリプトの保存先 スクリプトファイル名
tutorials [CRI] tutorial02-1_new_basic_project.py

スクリプトの説明

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

# --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_Tutorial
プロジェクトの保存先 PCの"Documents/CRIWARE/CriAtomCraft/projects"
チュートリアル用波形ファイルの場所 チュートリアルフォルダーの "tutorials/robot/local/tutorial_data"

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

# 作成するプロジェクト名
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__ に実行ファイルのパスが格納されています。
チュートリアルで使用する波形ファイルは、実行スクリプトファイルの2つ上のディレクトリーの「tutorial_data」フォルダーにあります。
os.path.dirnameを2回実行して、2つ上のディレクトリーを取得し、'tutorial_data'をチュートリアル用波形ファイルの場所に指定しています。

変数について
「project_name = "Project_Tutorial"」のように ”=” で結ばれた左側の値(「project_name」)を変数と呼びます。
変数は、プログラムで利用するデータを一時的に格納する入れ物のようなもので、数字、文字など様々なデータを入れることができます。
変数に格納しておくと、その後の処理で変数のデータを自由に取り出すことができるようになります。

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

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

関数名 説明
create_project プロジェクトを作成します
create_workunit ワークユニットを作成します

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

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

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

条件分岐 if文 について
プロジェクト作成の成否で「 if not result["succeed"]: 」の if ~ の文を使いました。
「ある特定の条件を満たす場合、何か処理をする」という仕組みを条件分岐と呼び次のように書きます。
if 条件式:
    処理
    処理
if文をよく見てみると処理の部分が、インデント(字下げ)しています。
Pythonでは、このインデントした範囲が制御文の処理対象になり、この範囲をコードブロックと呼びます。
Pythonでは一般的に半角空白文字4つ分のインデントをします。

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

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

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

create_project関数、create_workunit関数を実行した結果をresult変数に格納しました。
この関数から返される値を「戻り値」と言います。
この戻り値には、関数を実行した結果の様々な情報が格納されます。
戻り値に格納される情報を使って、CRI Atom Craftの情報を取得し、操作が行えるようになります。

マテリアル登録

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

関数名 説明
get_material_rootfolder ワークユニットのマテリアルルートフォルダーを取得します
register_material 波形ファイルを登録しマテリアルを作成します

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

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

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

戻り値の一部情報のみの利用について
get_material_rootfolder関数や register_material関数では、次のように戻り値の一部の情報 ["data"] のみを取得する記述になっています。
material_root_folder = acproject.get_material_rootfolder(workunit)["data"]
戻り値全ての情報が必要なく、戻り値の一部の情報のみで良い場合、関数の後ろに「 ["取得するキー"] 」を加えて戻り値の一部だけを取得することもできます。
このように記述することにより、戻り値全体を取得後、必要な情報を抜き出すといった記述の簡略化ができます。

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

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

関数名 説明
get_cuesheet_rootfolder ワークユニットのキューシートルートフォルダーを取得します
get_child_object 親オブジェクトを指定して、子オブジェクトを取得します
create_object タイプを指定してオブジェクトを作成します
create_waveform_region ウェーブフォームリージョンを作成します

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

# ----- キューシート・キューの作成 -----
# キューシートフォルダを取得
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関数に、「作成先のトラック情報」「参照するマテリアル」を指定して作成しています。

ここでは、オブジェクトの階層構造理解のためにcreate_object関数、create_waveform_region関数を使って、キュー、トラック、ウェーブフォームリージョンを1つずつ順に作成する方法を紹介しました。
projectモジュールにはこの他、拡張子を除いたマテリアル名をキュー名として使用することで、1つの関数にてキュー、トラック、ウェーブフォームリージョンまでの作成を行う「create_simple_cue」という関数も用意しています。
今回作成したスクリプトの「キュー、トラック、ウェーブフォームリージョン」の作成を、create_simple_cueで記述すると次のようになり、より少ないコードでキュー作成を行うことができます。
cue = acproject.create_simple_cue(cuesheet, material)["data"]

プロジェクト保存

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

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

関数名 説明
save_project_all プロジェクトを保存します

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

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

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