CRI ADX  Last Updated: 2024-07-17 10:47 p
Creating a Cue Sheet using CSV

In this tutorial, we will write a Script by using the CSV file to perform the operations as follows:

  • Create a Cue Sheet with a CSV file name
  • Registering Waveform files
  • Creating Cues
Waveform file name Cue name Cue ID Comment
Alert.wav SE1000_Alert 1000 Alarm
Attack_03.wav SE1001_Attack 1001 Attacks
ObjectAppearance.wav SE1002_ObjectAppearance 1002 Appears
~ ~ ~ ~

This tutorial will use the project created by Creating a project and registering Waveform file to a Cue tutorial.
Before starting this tutorial, if this project is not open, please open the project or execute the Script created in the Creating a project and registering Waveform file to a Cue tutorial.

Preparing a Script file

Select "Script list..." in the Script menu to display the Script list window.
Click the New button in the Script list window to create a Script file with the name below:

Save location of Script Script file name
tutorials [CRI] tutorial07-1_importcsv.py

Script Description

Double-click the created Script to open by Run the Script from the Script Editor .
In order to get an overview of the Script in the Script list window, write the Script description as follows:

# --Description:[Tutorial]Creating a Cue Sheet using the CSV

Importing Module

Once you have written the Script description, import the following modules to work with CRI Atom Craft in your Script.

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

Import the Python standard library's "csv" Module in order to read the CSV files.
Import the Project Module to work with the project and import the Debug Module for log output.

Waveform file folder and the path setting of the CSV file to import

Sets the CSV path to read.
Specifies the tutorial_data3.csv under the tutorial Waveform file folder ’tutorial_data/tutorial_data03’.

Write a Script for these processes as follows:

# Waveform file folder and the path setting of the CSV file to import
# Folder path of the Waveform file
data_dir = os.path.dirname(os.path.dirname(__file__)) + '/tutorial_data/tutorial_data03'
# Path of the CSV file
csv_path = data_dir + "/tutorial_data3.csv"
# Check if the CSV file exists
if os.path.isfile(csv_path) == False:
acdebug.log("CSV file not found: " + csv_path)
sys.exit()

Description of Waveform file folder and path setting of the CSV file to import

Only the Waveform file name is written in the CSV file to read, not the full path of the Waveform file.
Therefore, you need to register the Waveform file using the register_material function to specify the full path.
Define both the Waveform file folder path " data_dir " and the CSV path " csv_path " to create the Waveform file's full path later.
If the file does not exist, the Script can be interrupted by the os.path.isfile function to check if the file exists.

Getting Material folder and creating Cue Sheet

Waveform file name and the information of the Cue to create are written in the CSV information that was read.
Use the following function to perform the get Material folder for registering Waveform files and Cue Sheet creation for creating Cues.

Function name Description
get_workunit Gets the Work Unit
get_material_rootfolder Gets Work Unit's Material root folder
get_cuesheet_rootfolder Gets the Cue Sheet root folder of Work Unit
create_object Creates object by specifying type

Uses the CSV file name without the extension for the name of the Cue Sheet to create.
Write a Script for these processes as follows:

# Get a Work Unit
workunit = acproject.get_workunit("WorkUnit_Tutorial")["data"]
material_root_folder = acproject.get_material_rootfolder(workunit)["data"]
# Cue Sheet root folder
cuesheet_rootfolder = acproject.get_cuesheet_rootfolder(workunit)["data"]
# Extract the file name without extension
cuesheet_name = os.path.splitext(os.path.basename(csv_path))[0]
# Create a Cue Sheet by specifying the file name as the Cue Sheet name
cuesheet = acproject.create_object(cuesheet_rootfolder, "CueSheet", cuesheet_name)["data"]

Description of extracting file names without extension

To extract the file names without extension from the CSV path, use "os" Module's "os.path.splitext" function and "os.path.basename" function.
"os.path.basename" function gets the file name from the path string.
"os.path.splitext" function splits the string at the last(rightmost) dot, i.e. "." .
You can thus combine these two functions to get the file name without extension.

Open the CSV file

Below is the process of actually reading the CSV file, registering Material and creating Cues.
Use "csv" module's "csv.reader" function to read the CSV file.
Opens the file using the "open" function, gets the file object and specifies the "csv.reader" function.

# Open and read the CSV file
with open(csv_path) as f:
reader = csv.reader(f)
Note
About "with" Block
If you use the "open" function, you can also write "f = open("file path")" without using "with" Block.
However, in this case, you need to close the file manually with the "close" function after finishing reading the file.
The "with" Block function is convenient for closing automatically at the end of the Block.

Creating data from the CSV file(registering Waveform file and creating Cue Sheet and Cue)

Use the following function to read the content of the CSV file line by line, register Material or creating Cues.

Function name Description
register_material Registers the Waveform file and creates Material
create_simple_cue Creates a new simple Cue with information from Material
set_values Sets the parameter of the specified object in bulk
Uses an associative array to specify the strings of the key as the field name and value as the parameter value.

Write a Script for these processes as follows:

for row in reader:
wave_file_path = "" # For saving the Waveform file path
row_params = {} # For saving the parameter information of Cue
# Get each row of the CSV
wave_file_path = data_dir + "/" + row[0] # Waveform file name
row_params["Name"] = row[1] # Cue name
row_params["CueID"] = row[2] # Cue ID
row_params["Comment"] = row[3] # Comment
# Register the Waveform file and create Material
material = acproject.register_material(material_root_folder , wave_file_path)["data"]
# Create a Cue from Material
cue = acproject.create_simple_cue(cuesheet, material)["data"]
# Update the Cue name, Cue ID and Comment of a Cue
acproject.set_values(cue, row_params)
acdebug.log("[Tutorial]Creating a Cue Sheet using the CSV is completed.")

Description of creating data from the CSV file

Use the "for" control statement to get the CSV content line by line from the "reader" variable.
The obtained CSV data is stored in "<b>row</b>" in an array, and is divided by "<b>,</b>(comma)". In the "row", the saving order is "Waveform file name, Cue name, Cue ID, Comment".
It will get the information one by one, register the waveform file, create the Material, and create the Cue. For this created Cue, use set_values to set the "Cue name, Cue ID, Comment" information from the CSV. It will be stored in an associative array.

Saving the project

After introducing how to write the Script description for registering a Waveform file from the CSV file and creating a Cue, we will introduce how to save the project in the Script.

# Save Project
result = acproject.save_project_all()
if not result["succeed"]:
acdebug.warning("Failed to save the project file.")

Saving and running the Script

This concludes the scripting portion of this tutorial.
Save and run the Script.
If the Script runs successfully, it will create the Cue Sheet "tutorial_data3" according to the CSV information and create a Cue in it, as shown below.