Getting the Source

You can check out the source from the public Subversion repository:

svn co http://www.soundepartment.com/svn/agent-orange/trunk

This will pull the trunk down onto your local machine and put a copy of it onto your home directory. If you make any changes you'd like to see in the program, email me the svn diff and if it works and doesn't break anything else, I'll apply the patch. I'll make releases when significant bugs are fixed or significant functionality is added.

The code requires ruby 1.8.2 or better.

About the Source

The Agent Orange application that I distribute is actually made up of two distinct pieces:

1. A Mac OS X application called "Agent Orange", which is actually a special folder that acts as a wrapper for the functional components of the package. The Agent Orange application is a very short Objective-C program which merely takes the numbers and text you type in and feeds them on to the engine, which actually reads the text files and makes the PDF. You can find the code for this in the "osx" folder in the source repository.

2. "agent-orange", the Agent Orange engine, a collection of scripts written in the Ruby programming language. These do all the heavy-lifting of parsing the text export, managing all the timecodes and descriptions, interpreting tags, and then drawing the PDF out. "agent-orange" itself is a shell script that calls your installed version of ruby, reads the text export, and manipulates it with a variety of functions provided in a library. You can find the code for this in the "ruby" folder in the source repository.

Roadmap/To Do

1. The PDF drawing function in pdf.qs must be reworked. A lot of this functionality could be moved into new classes.
2. Track headings sometimes print funny.
3. The code requires better documentation.

Source Layout

The source is structured into a few executable scripts that provide main loops, and a series of libraries which provide functionality.

• bin/ Folder - The bin directory holds the execultable scrips that read the text exports and expose user-configurable options.
  • agent-orange.rb - This script accepts a text file and outputs a PDF cuesheet. It is the script that runs when you click Create PDF...
  • ao-qc.rb - The Agent Orange Cue-Cleaner. This script behaves like the agent-orange.rb script, except that it outputs a plain text file that has had tagged regions interpreted. This script is run when you click Create Text....
  • ao-info.rb - This is a very small script that quickly reads the session name and the number of tracks from a text export. The Agent Orange application uses it to create the default Cuesheet Title.
• lib/ Folder - This folder holds all of the libraries that agent-orange needs to do its thing. The agent-orange script includes the folder by its path relative to the script, and thus the lib folder must be present in the same directory as the agent-orange script. In actual distributions, I also include an ext folder in order to include my external dependencies, like pdf/writer and its dependencies.
  • pt/ Folder - This folder contains libraries which process Pro Tools text files and allows them to be represented programmatically.
  • pdf_qs.rb - This file contains a (rather too large) function that reads a session object as created by the text file and generates a PDF from it. This file is the core of the imaging functionality; it is also a huge mess.
  • blender.rb - A Blender object reads a track from a session and blends the regions together; when tags are being interpreted, the Blender class and the TagInterpreter class work together to make an interpreted track.
  • tag_interpreter.rb - This library contains the TagInterpreter object class; instances of TagInterpreter reads tracks in a session and output tracks with the tagging read (they also strip the tags off in the process).
• tests/ Folder - This folder contains the test cases and Unit Tests for the agent-orange system. You don't actually need this folder in order to run Agent Orange, but this folder is important to developers.
  • tagging_tests.rb - This file contains a few foundational tests of the TagInterpreter. Reading it, you can see that a new track is created in a test context, filled with a few tagged tracks, and then interpreted. The result is then compared against a set of criteria to see if the TagInterpreter did the right thing.
• tagging_test_cases/ - This folder contains some systematic tests of the TagInterpreter and the text-export system. The folder contains an in folder and an out folder. Both folders contain text exports; text files in the in folder are imported and then have their tags interpreted. The interpreted text is then compared against the file in the out folder with the same name. If the two match, the test passes. These tests occur as a part of the test suite, the machinery that runs them is in tests/tagging_test_cases.rb.