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

スクリプトファイルの準備
モジュールのインポート
プロジェクト名、プロジェクト保存先の設定
プロジェクト作成、ワークユニット作成
マテリアル登録
プロジェクト保存

オブジェクト作成の基本方法について習得しましょう。

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

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

スクリプトの保存先	スクリプトファイル名
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 Craft のプロジェクトデータを操作する project モジュールをインポートしています。

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

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

項目	内容
プロジェクト名	TutorialProject_Robot
プロジェクトの保存先	PC の "Documents/CRIWARE/CriAtomCraft/projects"
チュートリアル用波形ファイルの場所	チュートリアルフォルダーの "tutorials/robot/local/tutorial_data"

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

# 作成するプロジェクト名
project_name = "TutorialProject_Robot"
 
# プロジェクトを作成する場所
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'をチュートリアル用波形ファイルの場所に指定しています。

覚え書き: 変数について
「project_name = "TutorialProject_Robot"」のように ”=” で結ばれた左側の値(「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」を含んだ「TutorialProject_Robot」プロジェクトが作成されます。

プロジェクト作成の解説

プロジェクトを作成する create_project 関数には、「プロジェクト名」、「プロジェクト保存先」、「プロジェクトの上書きするか」の３つの情報を指定します。
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_rootfolder = acproject.get_material_rootfolder(workunit)["data"]
 
# マテリアルルートフォルダに波形ファイルを登録
material = acproject.register_material(material_rootfolder, data_dir+"/tutorial_data01/gun1_High.wav")["data"]

マテリアル登録の解説

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

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

覚え書き: 戻り値の一部情報のみの利用について
get_material_rootfolder 関数や register_material 関数では、次のように戻り値の一部の情報 ["data"] のみを取得する記述になっています。

material_rootfolder = 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 関数に、「作成先のトラック情報」「参照するマテリアル」を指定して作成します。

覚え書き: get_child_object 関数、 create_object 関数で指定するオブジェクトタイプ名については、オブジェクトリファレンスを参照してください。

覚え書き: ここでは、オブジェクトの階層構造理解のために create_object 関数、 create_waveform_region 関数を使って、キュー、トラック、ウェーブフォームリージョンを１つずつ順に作成する方法を紹介しました。
project モジュールにはこの他、拡張子を除いたマテリアル名をキュー名として使用することで、１つの関数にてキュー、トラック、ウェーブフォームリージョンまでの作成を行う「 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("プロジェクトファイルの保存に失敗しました。")