项目的创建和在Cue上注册波形文件

本教程将按照以下顺序编写脚本，以执行从项目的创建到在Cue中注册波形文件处理。

• 脚本文件的准备
• 模块的导入
• 项目名称、项目保存目标设置
• 创建项目和工作单元
• 素材注册
• 保存项目

以下为创建对象的基本方法。

脚本文件的准备

选择脚本菜单上的“脚本列表...”显示脚本列表窗口。
单击脚本列表窗口的[新建]按钮，以创建名称如下的脚本文件：

脚本的保存目标	脚本文件名
tutorials [CRI]	tutorial02-1_new_basic_project.py

脚本说明

双击已创建的脚本，用 从脚本编辑器运行脚本 打开。
要通过脚本列表窗口确认脚本概要，按照以下脚本说明来编写。

# --Description:[教程]创建和保存从项目到Cue的基本播放数据

模块的导入

编写脚本说明后，导入以下模块来用脚本操作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的操作模块。
请在 在脚本日志上显示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 函数中指定“项目名”、“项目保存目标”和“是否覆盖项目”的三项信息。
将"是否覆盖项目"指定为True时，则即使在项目保存目标内存在同名的项目文件，也将覆盖该文件并创建一个新项目。
执行该函数时，结果将作为返回值返回。
并保存在 result 变量中。

result 变量内保存了函数执行结果的各种信息，您可以使用识别字符（键）取出信息。
使用"succeed"键来获取执行函数是否成功。
获取保存在result变量中的 "succeed" 键的信息，并确认创建项目成功与否。
项目的创建失败时，将输出日志并终止脚本执行。

注解

关于条件分歧 if 语句
使用“ if〜”语句（" if not result["succeed"]: "）来检查创建项目是否成功。
条件分歧（即满足某些指定条件，将处理某种处理的机制）的编写方式如下：

if 条件表达式：
     处理
     处理

缩进用于if语句。
在Python中将此缩进范围是控制语句的处理目标，而该范围称为代码块处理的范围。
通常在Python中使用4个半角空白字符来缩进。

创建工作单元的解说

在要创建的工作单元的 create_workunit 函数指定“工作单元名”、“是否在工作单元管理素材”和“创建Cue时设置的总线图”的信息。
执行 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"]

无需返回值的所有信息而仅需要返回值的部分信息时，请在函数后面添加“["要获取的Key"] ”。
通过以上编写可以简化在获取所有返回值后，再获取需要的信息。

创建Cue Sheet、Cue和波形区域

以上步骤显示了如何在工作单元的素材信息中注册波形文件。
使用下述函数创建Cue Sheet及其下的Cue，在Cue中注册素材以创建波形区域。

函数名	项目
get_cuesheet_rootfolder	获取工作单元的Cue Sheet根文件夹
get_child_object	指定父对象后获取子对象
create_object	指定类型后创建对象
create_waveform_region	创建波形区域

使用以上函数来创建Cue Sheet、Cue和设置素材可以如下编写脚本。

# ----- Cue Sheet或Cue的创建 -----
# 获取Cue Sheet文件夹
cuesheet_rootfolder = acproject.get_cuesheet_rootfolder(workunit)["data"]

# 获取Cue Sheet文件夹“WorkUnit_Tutorial”
cuesheet_folder = acproject.get_child_object(cuesheet_rootfolder, "CueSheetFolder", "WorkUnit_Tutorial")["data"]

# 在Cue Sheet文件夹中创建Cue Sheet
cuesheet = acproject.create_object(cuesheet_folder, "CueSheet", "Tutorial")["data"]

# ----- 创建Cue/音轨/波形区域 -----
# 创建Cue
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"]

创建Cue Sheet的解说

要获取Cue Sheet创建目标的文件夹，请使用 get_cuesheet_rootfolder 函数来获取工作单元的Cue Sheet根文件夹。
然后，使用 get_child_object 函数来获取Cue Sheet根文件夹正下方的 "WorkUnit_Tutorial" 文件夹。
在 get_child_object 函数中指定“获取源的对象信息”、“要获取的对象类型”和“要获取的对象名称”。

"WorkUnit_Tutorial"文件夹是与工作单元同名的文件夹，在创建工作单元时会自动创建。
通过在此文件夹中创建Cue Sheet，可以各工作单元为单位分离ACB（游戏数据）的输出目标。

通过指定已获取的创建目标的Cue Sheet文件夹、Cue Sheet对象类型 "CueSheet"和Cue Sheet名 "Tutorial" ，使用 create_object 函数(通用对象创建函数)来创建了Cue Sheet。
在 create_object 函数中指定“创建源的对象信息”、“要创建的对象类型”和“要创建的对象名称”。

创建Cue、音轨和波形区域的解说

在已创建的Cue Sheet上依次创建Cue、音轨和波形区域。
要了解为何要在创建波形区域之前需要Cue和音轨，请参照 CRI Atom Craft的对象结构 中的对象结构。
Cue、音轨和波形区域是属于层级关系。
与Cue Sheet相同，使用 create_object 函数来创建Cue和音轨。
在专用的 create_waveform_region 函数指定“创建目标的音轨信息”和“要参照的素材”来创建波形区域。

注解

关于 get_child_object 函数和 create_object 函数指定的对象类型名，请参照 参照型对象 。

注解

为了帮助理解对象的层级结构，本节介绍了如何使用 create_object 函数和 create_waveform_region 函数依次逐个创建Cue、音轨和波形区域。
除 Project模块 外，还具有 create_simple_cue 函数。 该函数通过使用不带扩展名的素材名称作为Cue名称，可以在一个函数中创建Cue音轨、波形区域。
使用 create_simple_cue 如下编写脚本来创建脚本中的“Cue、音轨和波形区域”，可以用更少的代码来创建Cue。

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

保存项目

以上步骤显示了如何创建项目后，使用注册的波形文件创建Cue。
最后，保存已创建的项目并终止本教程。

项目的保存使用下述函数。

函数名	项目
save_project_all	保存项目

使用此函数保存项目可以如下编写脚本。

## 项目的保存
result = acproject.save_project_all()

# 保存失败，请检查结果。失败时则输出讯息。
if not result["succeed"]:
    acdebug.warning("项目文件保存失败。")