Chapter 9. Tutorial 9: Automating and Scripting athenaCL

Table of Contents
9.1. The athenacl Command-Line Utility
9.2. Creating an athenaCL Interpreter within Python
9.3. Creating athenaCL Generator ParameterObjects within Python

This tutorial demonstrates some of the many ways the athenaCL system can be automated, scripted, and used from the shell and within the Python programming language. Such usage is primarily only for advanced users.

9.1. The athenacl Command-Line Utility

On UNIX-based environments such as GNU/Linux, MacOS X, and BSD, athenaCL can be controlled and automated from the command-line shell without directly entering the athenaCL Interpreter. The athenacl command-line utility should be installed according to the directions specified in Appendix A. Either directly from the command line, or through the use of shell scripts or shell calls from other programs, the complete functionality of athenaCL is available.

The athenacl command-line tool provides a flag, "-e", with which to delimit any number of complete athenaCL commands and command-line arguments. Arguments following the -e flag, in most circumstances, should be enclosed in quotes.

In the following simple example the user, using the athenacl command-line tool, calls from the shell (with the prompt "%") the AUpc command to view pitch information for 9000 hertz. Each command and its arguments are included in quotes. The optional "confirm" argument is used with the q command to immediately quit athenaCL without confirmation.

Example 9-1. Calling a command with arguments from the UNIX shell

% athenacl -e "aupc 9000hz" -e "q confirm"

athenaCL 1.4.0 (on darwin via terminal threading off)
Enter "cmd" to see all commands. For help enter "?".
Enter "c" for copyright, "w" for warranty, "r" for credits.

:: AUpc 9000hz
AthenaUtility Pitch Converter
format              fq        
name                C#~9      
midi                121       
pitch-class         1         
pch                 13.0125   
frequency           9000.0000 
pitch-space         61.25     

:: q confirm

% 

In the following example the user calls a number of athenaCL commands with complete arguments to create Textures and an EventList. Using EventMode midiPercussion, three LineGroove Textures, each with a different instrument number, are created. Each Texture's rhythm is edited with TIe, and then the amplitudes and tempi (bpm) of the ensemble of Textures is edited with TEe. A new EventList is created and auditioned. Note that, as when using complete command-line arguments within the athenaCL Interpreter, ParameterObject argument lists may not include any spaces. (Replace "/Volumes/xdisc/_scratch/" with a complete file path to a suitable directory.)

Example 9-2. Creating and editing Textures from the UNIX shell

% athenacl -e "emo mp" -e "tmo lg" -e "tin a1 36" -e "tie r 
l,((4,3,1),(4,3,0),(4,2,1)),rc" -e "tin b1 37" -e "tie r
l,((4,6,1),(4,1,1),(4,3,1)),rc" -e "tin c1 53" -e "tie r
l,((4,1,1),(4,1,1),(4,6,0)),rw" -e "tee a bg,rc,(.5,.7,.75,.8,1)" -e "tee b
ws,t,4,0,122,118" -e "eln /Volumes/xdisc/_scratch/a.xml" -e "elh" -e "q
confirm"

athenaCL 1.4.0 (on darwin via terminal threading off)
Enter "cmd" to see all commands. For help enter "?".
Enter "c" for copyright, "w" for warranty, "r" for credits.

:: EMo mp
EventMode mode set to: midiPercussion.

:: TMo lg
TextureModule LineGroove now active.

:: TIn a1 36
TI a1 created.

:: TIe r l,((4,3,1),(4,3,0),(4,2,1)),rc
TI a1: parameter rhythm updated.

:: TIn b1 37
TI b1 created.

:: TIe r l,((4,6,1),(4,1,1),(4,3,1)),rc
TI b1: parameter rhythm updated.

:: TIn c1 53
TI c1 created.

:: TIe r l,((4,1,1),(4,1,1),(4,6,0)),rw
TI c1: parameter rhythm updated.

:: TEe a bg,rc,(.5,.7,.75,.8,1)
TI a1: parameter amplitude updated.
TI c1: parameter amplitude updated.
TI b1: parameter amplitude updated.

:: TEe b ws,t,4,0,122,118
TI a1: parameter bpm updated.
TI c1: parameter bpm updated.
TI b1: parameter bpm updated.

:: ELn /Volumes/xdisc/_scratch/a.xml
   EventList a complete:
/Volumes/xdisc/_scratch/a.mid
/Volumes/xdisc/_scratch/a.xml

:: ELh
EventList hear initiated: /Volumes/xdisc/_scratch/a.mid

:: q confirm

%