{"id":4371,"date":"2023-06-22T16:12:19","date_gmt":"2023-06-22T07:12:19","guid":{"rendered":"https:\/\/blog.criware.com\/?p=4371"},"modified":"2024-05-17T19:15:54","modified_gmt":"2024-05-17T10:15:54","slug":"getting-started-with-the-robot-api","status":"publish","type":"post","link":"https:\/\/blog.criware.com\/index.php\/2023\/06\/22\/getting-started-with-the-robot-api\/","title":{"rendered":"Getting started with the Robot API"},"content":{"rendered":"<p>The Robot API of Atom Craft makes it possible to automate workflows in the authoring tool by writing Python scripts.<\/p>\n<p>It can be used for instance for the registration of large amounts of assets in a project, for the batch-editing of properties, or to build integrations with other tools, such as DAWs.<\/p>\n<p>By reducing the number of repetitive tasks to perform and by minimizing potential mistakes, it will undoubtedly increase the efficiency of your sound team!<\/p>\n<p>The Robot API comes installed with Atom Craft. It already includes many useful scripts, that can also be used as references for your own efforts.<\/p>\n<h2 style=\"font-size: 150%; font-weight: bold; margin-top: 40px;\">Configuration<\/h2>\n<h3 style=\"font-size: 16px; font-weight: bold; text-decoration: underline;\">1. Installing Python<\/h3>\n<p>To use the Robot API, Python must to be installed. At the time of this writing, <strong>Atom<\/strong><strong> Craft ver. 3.48.02 supports Python version 3.7, 3.8 or 3.9.<\/strong> If you are using a more recent version of AtomCraft, please check the latest compatibility list in the documentation.<\/p>\n<ul>\n<li>Download a version of Python compatible with AtomCraft from <a href=\"https:\/\/www.python.org\/\">https:\/\/www.python.org\/<\/a><\/li>\n<li>During the installation, check \u201cAdd Python to environment variables\u201d in the advanced options.<\/li>\n<\/ul>\n<p style=\"text-align:center;\">\n<img loading=\"lazy\" decoding=\"async\" src=\"https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/01-Python-1.jpg\" alt=\"Created with GIMP\" width=\"666\" height=\"410\" class=\"size-full wp-image-4382\" \/>\n<\/p>\n<p>If you forgot, you will still be able to do it manually later by assigning your installation path to the PYTHONHOME and PATH environment variables.<\/p>\n<h3 style=\"font-size: 16px; font-weight: bold; text-decoration: underline;\">\n2. Configuring Atom Craft<br \/>\n<\/h3>\n<ul>\n<li>In AtomCraft, select the <em>Script &gt; Script Settings &gt; Plugin<\/em> menu command.<\/li>\n<li>For the <em>Plugin Type<\/em><em>,<\/em> choose the version of Python you just installed.<\/li>\n<\/ul>\n<p style=\"text-align:center;\">\n<img loading=\"lazy\" decoding=\"async\" src=\"https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/02-Atom-Craft-Python.jpg\" alt=\"02 - Atom Craft Python\" width=\"470\" height=\"280\" class=\"alignnone size-full wp-image-4384\" srcset=\"https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/02-Atom-Craft-Python.jpg 470w, https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/02-Atom-Craft-Python-300x179.jpg 300w\" sizes=\"auto, (max-width: 470px) 100vw, 470px\" \/>\n<\/p>\n<ul>\n<li>Finally, you can specify the folders in which Atom Craft will look for script files. To add new folders, go to the <em>User Script<\/em> tab, and click on the <em>Add<\/em> button. The scripts located in these folders will be accessible via the <em>Script List<\/em> and <em>Script Menu<\/em>.<\/li>\n<\/ul>\n<p style=\"text-align:center;\">\n<img loading=\"lazy\" decoding=\"async\" src=\"https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/03-User-Scripts.png\" alt=\"03 - User Scripts\" width=\"470\" height=\"356\" class=\"alignnone size-full wp-image-4386\" srcset=\"https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/03-User-Scripts.png 470w, https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/03-User-Scripts-300x227.png 300w\" sizes=\"auto, (max-width: 470px) 100vw, 470px\" \/>\n<\/p>\n<h2 style=\"font-size: 150%; font-weight: bold; margin-top: 40px;\">Hello, World<\/h2>\n<p>Before starting, keep in mind that the Robot API directly manipulates the data structure of\u00a0 the project in Atom Craft. The overall data structure is fixed and divided into 3 trees &#8211; &#8220;Project&#8221;, &#8220;Work Unit&#8221;, and &#8220;Material&#8221;.<\/p>\n<p>Atom Craft comes with an IDE to write your own scripts. You can also use any external editor if needed, but if you are just getting into scripting, it is probably the easiest way to start.<\/p>\n<p>To create our first script:<\/p>\n<ul>\n<li>Go to the <em>Script<\/em> menu and select<em> Script List <\/em>to open the list of scripts.<\/li>\n<li>Then, under tutorials or in your own folder (if you previously added one), click on the <em>New<\/em> button, name the script \u201cHello World\u201d and click on <em>Save<\/em>.<\/li>\n<\/ul>\n<p style=\"text-align:center;\">\n<img loading=\"lazy\" decoding=\"async\" src=\"https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/04-Script-list.png\" alt=\"04 - Script list\" width=\"842\" height=\"570\" class=\"alignnone size-full wp-image-4387\" srcset=\"https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/04-Script-list.png 842w, https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/04-Script-list-300x203.png 300w, https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/04-Script-list-768x520.png 768w\" sizes=\"auto, (max-width: 842px) 100vw, 842px\" \/>\n<\/p>\n<ul>\n<li>Select your newly created script and click on the <em>Edit<\/em> button to open the <em>Script Editor<\/em>.<\/li>\n<\/ul>\n<p>We will first write a script to display \u201cHello, World\u201d in the Atom Craft log.<\/p>\n<ul>\n<li>Start by writing a comment to describe our script.<\/li>\n<li>The Script list will detect a comment written in a specific format and display it in the list\u2019s \u201cDescription\u201d field.<\/li>\n<\/ul>\n<pre><code>\r\n# --Description: Displaying \"Hello, World\" in the Script log\r\n<\/code><\/pre>\n<ul>\n<li>Once your comment is input, click the Save button. The description in the Script List will be automatically updated.<\/li>\n<\/ul>\n<p style=\"text-align:center;\">\n<img loading=\"lazy\" decoding=\"async\" style=\"border: 1px solid #333;\" src=\"https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/05-Description.png\" alt=\"05 - Description\" width=\"703\" height=\"263\" class=\"alignnone size-full wp-image-4388\" srcset=\"https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/05-Description.png 703w, https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/05-Description-300x112.png 300w\" sizes=\"auto, (max-width: 703px) 100vw, 703px\" \/>\n<\/p>\n<p>The Robot API comes with external Python modules for manipulating Atom Craft data. For example, here we will need the Debug Module. To use an external Python module, write <em>import<\/em> and the name of the module:<\/p>\n<pre><code>\r\nimport cri.atomcraft.debug\r\n<\/code><\/pre>\n<ul>\n<li>The Debug module provides several string output functions. We will use the <em>log<\/em> function to display &#8220;Hello, World&#8221;:<\/li>\n<\/ul>\n<pre><code>\r\ncri.atomcraft.debug.log(\"Hello, World\")\r\n<\/code><\/pre>\n<ul>\n<li>Note that you can also use the <em>warning<\/em> function to display a highlighted string in the Atom Craft log tab:<\/li>\n<\/ul>\n<pre><code>\r\ncri.atomcraft.debug.warning(\"Hello, World\")\r\n<\/code><\/pre>\n<ul>\n<li><em>Save<\/em><em>,<\/em> <em>Run<\/em> the script, and check its output in the log.<\/li>\n<\/ul>\n<p style=\"text-align:center;\">\n<img loading=\"lazy\" decoding=\"async\" style=\"border: 1px solid #333;\" src=\"https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/06-Hello-world-script.png\" alt=\"06 - Hello world script\" width=\"846\" height=\"328\" class=\"alignnone size-full wp-image-4389\" srcset=\"https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/06-Hello-world-script.png 846w, https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/06-Hello-world-script-300x116.png 300w, https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/06-Hello-world-script-768x298.png 768w\" sizes=\"auto, (max-width: 846px) 100vw, 846px\" \/>\n<\/p>\n<h2 style=\"font-size: 150%; font-weight: bold; margin-top: 40px;\">Creating a Cue<\/h2>\n<p>Finally, we will write a simple script that adds a new Cue to the selected CueSheet. After creating a new script in the Script List window and writing a description, let\u2019s import the modules we will need.<\/p>\n<ul>\n<li>In addition to the Python&#8217;s standard modules &#8220;sys&#8221; and &#8220;os\u201d, we will import the Debug Module that we already have used, and the Project Module to be able to work with the project data of Atom Craft.<\/li>\n<\/ul>\n<pre><code>\r\nimport sys\r\nimport os\r\nimport cri.atomcraft.debug as acdebug\r\nimport cri.atomcraft.project as acproject\r\n<\/code><\/pre>\n<p>By adding \u201cas\u201d and a name after an imported module, this name can be used as an alias to reference the module (here \u201cacdebug\u201d and \u201cacproject\u201d for cri.atomcraft.debug and cri.atomcraft.project, respectively), making the script more readable.<\/p>\n<p>Now we must get the selected Cue Sheet. The <em>get_selected_objects <\/em>function will return all the selected objects of a given type in an array. So, we passed the string \u201cCueSheet\u201d to only get the CueSheets.<\/p>\n<pre><code>\r\nselected_cuesheets = acproject.get_selected_objects(\"CueSheet\")[\"data\"]\r\n<\/code><\/pre>\n<ul>\n<li>Then we simply use the <em>create<\/em>_<em>object<\/em> function to create an object of a given type under a given name. The parent object in the project is also passed as an argument. Here, we select the first selected Cue Sheet that was returned, i.e. <em>selected<\/em><em>_cuesheet<\/em><em>s[0]<\/em>).<\/li>\n<\/ul>\n<pre><code>\r\ncue_name = \"My_Cue\"\r\nacproject.create_object(selected_cuesheets[0], \"Cue\", cue_name)[\"data\"]\r\n<\/code><\/pre>\n<p>After saving your script, you can now select a Cue Sheet in the <em>WorkUnits Tree<\/em> and <em>Run<\/em> the script to create a new cue called \u201cMy_Cue\u201d.<\/p>\n<p style=\"text-align:center;\">\n<img loading=\"lazy\" decoding=\"async\" style=\"border: 1px solid #333;\" src=\"https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/07-Create-a-Cue-Simple.png\" alt=\"07 - Create a Cue Simple\" width=\"1073\" height=\"394\" class=\"alignnone size-full wp-image-4390\" srcset=\"https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/07-Create-a-Cue-Simple.png 1073w, https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/07-Create-a-Cue-Simple-300x110.png 300w, https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/07-Create-a-Cue-Simple-768x282.png 768w, https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/07-Create-a-Cue-Simple-1024x376.png 1024w\" sizes=\"auto, (max-width: 1073px) 100vw, 1073px\" \/>\n<\/p>\n<p>This script could be improved, for example by first making sure that a Cue Sheet was actually selected before creating the new cue, and adding some feedback in the log. The final code could look like this:<\/p>\n<pre><code>\r\n# --Description: Create a new Cue in the Selected CueSheet\r\nimport sys\r\nimport os\r\nimport cri.atomcraft.debug as acdebug\r\nimport cri.atomcraft.project as acproject\r\n\r\n# Get the selected CueSheets\r\nselected_cuesheets = acproject.get_selected_objects(\"CueSheet\")[\"data\"]\r\n\r\n\r\n# Check if a CueSheet is selected\r\nif not selected_cuesheets:\r\n   acdebug.warning(\"Please select a CueSheet.\")\r\n   sys.exit()\r\n\r\nelse:\r\n# Get the name of the first selected CueSheet\r\n   cuesheet_name = acproject.get_value(selected_cuesheets[0], \"Name\")[\"data\"]\r\n\r\n# Create a Cue in the selected CueSheet\r\n   cue_name = \"My_Cue\"\r\n   acproject.create_object(selected_cuesheets[0], \"Cue\", cue_name)[\"data\"]\r\n\r\n   acdebug.log(f\"The Cue \\\"{cue_name}\\\" was created in the CueSheet \\\"{cuesheet_name}\\\"\")\r\n<\/code><\/pre>\n<div class=\"wp-video\" style=\"width: 800px; display: block; margin: 40px auto;\">\n<div style=\"width: 800px;\" class=\"wp-video\"><video class=\"wp-video-shortcode\" id=\"video-4371-1\" width=\"800\" height=\"422\" preload=\"metadata\" controls=\"controls\"><source type=\"video\/mp4\" src=\"https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/Video_Robot_Script_CreateCue.mp4?_=1\" \/><a href=\"https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/Video_Robot_Script_CreateCue.mp4\">https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/Video_Robot_Script_CreateCue.mp4<\/a><\/video><\/div>\n<\/div>\n<p>This concludes this introduction to the Robot API. With a bit of experimentation, you should be able to create new workflows and automations that will make using Atom Craft even more efficient. Stay tuned for future posts about the Robot API functions!<\/p>\n<div style=\"max-width: 800px; margin: 0 auto; margin-bottom: 20px; text-align: center;\"><a style=\"display: block; border: 1px solid #ccc; padding: 20px; max-width: 100%; margin: 0 auto;\" href=\"https:\/\/blog.criware.com\/wp-content\/uploads\/2023\/06\/AtomCraft_Robot_PythonScript_CreateCue.zip\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-full wp-image-1813\" style=\"display: block; margin: 0 auto;\" src=\"https:\/\/blog.criware.com\/wp-content\/uploads\/2018\/06\/zip.png\" alt=\"zip\" width=\"80\" height=\"78\" \/>AtomCraft_Robot_PythonScript_CreateCue.zip<\/a><\/div>\n<p>&nbsp;<\/p>\n","protected":false},"excerpt":{"rendered":"<p>The Robot API of Atom Craft makes it possible to automate workflows in the authoring tool by writing Python scripts.<\/p>\n","protected":false},"author":2,"featured_media":5412,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"colormag_page_container_layout":"default_layout","colormag_page_sidebar_layout":"default_layout","footnotes":""},"categories":[5,7],"tags":[],"class_list":["post-4371","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-adx","category-tutorials"],"aioseo_notices":[],"_links":{"self":[{"href":"https:\/\/blog.criware.com\/index.php\/wp-json\/wp\/v2\/posts\/4371","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blog.criware.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.criware.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.criware.com\/index.php\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.criware.com\/index.php\/wp-json\/wp\/v2\/comments?post=4371"}],"version-history":[{"count":20,"href":"https:\/\/blog.criware.com\/index.php\/wp-json\/wp\/v2\/posts\/4371\/revisions"}],"predecessor-version":[{"id":5411,"href":"https:\/\/blog.criware.com\/index.php\/wp-json\/wp\/v2\/posts\/4371\/revisions\/5411"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/blog.criware.com\/index.php\/wp-json\/wp\/v2\/media\/5412"}],"wp:attachment":[{"href":"https:\/\/blog.criware.com\/index.php\/wp-json\/wp\/v2\/media?parent=4371"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.criware.com\/index.php\/wp-json\/wp\/v2\/categories?post=4371"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.criware.com\/index.php\/wp-json\/wp\/v2\/tags?post=4371"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}