Batch Renaming with Robot API

12th July 2023 criware

In a previous post,we introduced the Robot API with some simple scripts to get you started. This time, we will dive a bit further into it, and write a script that will allow us to add a prefix and/or suffix to the names of the selected objects in Atom Craft.

User Variables

First, we will need to use the User Variables to be able to specify an object/string/value directly in the GUI instead of hard-coding it in the Script Editor.

User variables must be defined at the beginning of your script, inside a block delimited by # –BeginUserVariable and # –EndUserVariable. In order for a user variable to appear in the GUI – located on the right side of the Script Editor – the variable’s name, its type (object, string or number), and a description need to be specified in a “docstring” by using three double quotation marks (“””). The initial value for each variable is set on the following lines. Note that you need to import cri.atomcraft.project at the beginning of your script to define user variables.

For this batch renaming script, we need three user variables of type string:

OBJECT will define on what type of objects (Cues, Tracks, Materials…) we want to perform the renaming.
PREFIX is the string that will be added at the beginning of the name.
SUFFIX is the string that will be added at the end of the name.

Here is how to define them:


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

# --BeginUserVariable
"""
OBJECT:
  type:string
  comment:Type of object to rename
PREFIX:
  type:string
  comment:Prefix to add to the name of the object
SUFFIX:
  type:string
  comment:Suffix to add to the name of the object
"""
OBJECT = "Cue"
PREFIX = ""
SUFFIX = ""
# --EndUserVariable

Once the script is saved and reloaded, they will be displayed in the GUI. After changing the values in the GUI and clicking on the Apply button, the new values will be shown in the script.

Note that scripts with user variables are displayed with an icon in the Script list.

Script

Now that we have defined our user variables, we can start scripting. First, we must get the list of the objects selected in the AtomCraft trees:

In order to do that, we use the get_selected_objects function (check our previous post to see how to use it).
Instead of passing a specific string like last time we use our OBJECT user variable.

# Get the selected objects
selected_objects = acproject.get_selected_objects(OBJECT)["data"]

Next, we want to prevent the script from running if the selected objects are not of a specified type, or if nothing has been assigned to the OBJECT variable. On top of that, we also want to communicate the list of the valid object types to the user.

We start by defining the list of valid objects.
In this script, we only allowed for Cues, Materials, Cue Sheets, and Tracks to be renamed. But feel free to edit this list to suit your needs (you can check all the object types in the Object reference section of the Robot API documentation).

# List of valid objects
valid_objects = ["Cue", "Material", "CueSheet", "Track"]

Once the list of objects defined, we need to prevent the script from running:

If the OBJECT variable is empty.
If the OBJECT variable doesn’t correspond to an existing type of object.
If the OBJECT variable exists but doesn’t correspond to any of the selected objects.
If the OBJECT variable exists but is not referring to one of the valid types we defined.


# Get the selected objects
  selected_objects = acproject.get_selected_objects(OBJECT)["data"]

  # Check if the selected objects are of a valid type
  valid_objects = ["Cue", "Material", "CueSheet", "Track"]	# List of valid objects
  if not selected_objects:
    if OBJECT == "":
      acdebug.warning(f"Please specify the object type. Valid types are: {valid_objects}.")
    elif OBJECT not in valid_objects:
      acdebug.warning(f"This is not a valid type for the object. Please use one of these types: {valid_objects}.")
    else:
      acdebug.warning(f"Please select one or several {OBJECT}s.")
    sys.exit()

  elif OBJECT not in valid_objects:
    acdebug.warning(f"Only these types of objects can be renamed: {valid_objects}.")
    sys.exit()

Now that we ensured that the selected_objects are valid, we can add a prefix and/or a suffix to their names.

We use a for loop to go through the list of the selected_ objects and to get their names using the get_value function.
If the PREFIX variable is not empty, we concatenate the prefix string with the object name and store it in modified_object_name.
Similarly, if the SUFFIX variable is not empty, it is appended to the current object’s name stored in modified_object_name.
Since Material names include extensions (like .wav, .ogg), we make sure to call os.path.splitext before to split the object’s name into its base name and its extension, allowing us to insert the suffix before the extension (i.e., by concatenating the base name, suffix, and extension together).
Finally, we use the set_value function to replace the name of the object with the modified_object_name.


for obj in selected_objects:
  object_name = acproject.get_value(obj, "Name")["data"]
  modified_object_name = object_name

  if PREFIX != "":
    modified_object_name = PREFIX + object_name	# Add the prefix if not empty

  if SUFFIX != "":
    base_name, extension = os.path.splitext(modified_object_name)
    modified_object_name = base_name + SUFFIX + extension	# Add the suffix if not empty

  acproject.set_value(obj, "Name", modified_object_name)	# Change the object name to the new name
  acdebug.log(f"{OBJECT} - {object_name} has been renamed to {modified_object_name}")

Note that we also checked at that beginning of the script if both the PREFIX and SUFFIX variables were not empty.

Here is the final script:


# --Description: Add a prefix and/or a suffix to the name of the selected objects
import sys
import os
import cri.atomcraft.debug as acdebug
import cri.atomcraft.project as acproject

# --BeginUserVariable
"""
OBJECT:
  type:string
  comment:Type of object to rename
PREFIX:
  type:string
  comment:Prefix to add to the name of the object
SUFFIX:
  type:string
  comment:Suffix to add to the name of the object
"""
OBJECT = "Cue"
PREFIX = ""
SUFFIX = ""
# --EndUserVariable

if PREFIX != "" or SUFFIX != "":
  # Get the selected objects
  selected_objects = acproject.get_selected_objects(OBJECT)["data"]
  
  # Check if the selected objects are of a valid type
  valid_objects = ["Cue", "Material", "CueSheet", "Track"]	# List of valid objects
  if not selected_objects:
    if OBJECT == "":
      acdebug.warning(f"Please specify the object type. Valid types are: {valid_objects}.")
    elif OBJECT not in valid_objects:
      acdebug.warning(f"This is not a valid type for the object. Please use one of these types: {valid_objects}.")
    else:
      acdebug.warning(f"Please select one or several {OBJECT}s.")
    sys.exit()

  elif OBJECT not in valid_objects:
    acdebug.warning(f"Only these types of objects can be renamed: {valid_objects}.")
    sys.exit()

  else:
    for obj in selected_objects:
      object_name = acproject.get_value(obj, "Name")["data"]
      modified_object_name = object_name

      if PREFIX != "":
        modified_object_name = PREFIX + object_name	# Add the prefix if not empty

      if SUFFIX != "":
        base_name, extension = os.path.splitext(modified_object_name)
        modified_object_name = base_name + SUFFIX + extension	# Add the suffix if not empty

      acproject.set_value(obj, "Name", modified_object_name)	# Change the object name to the new name
      acdebug.log(f"{OBJECT} - {object_name} has been renamed to {modified_object_name}")

else:
  acdebug.warning("Please specify a Prefix or a Suffix.")

You can download the script below and try to add new renaming features. Stay tuned for future posts about the Robot API!

AtomCraft_Robot_PythonScript_BatchRenamer.zip