Scripting

versions concerned : 0.2 and above

I. Command-line parameters

Since version 0.2, the ARSS can be entirely operated using command-line parameters. These commands are listed by the program's help, which can be displayed by simply launching the program and typing help, or calling 'arss --help', 'arss -h' or even 'arss /?' on Windows.

There are only a few things to know in order to understand how to operate the program from the command line. Firstly, you can place any option or file name anywhere, with two exceptions. The input file must always come before the output file, and, obviously enough, each option which requires a number (which is denoted in the help by [real] or [integer]) must be immediately followed by this number. So, when you see the line '--pps, -p [real]', it means that you can write, for example, '--pps 133.33' or '-p 17.5' anywhere in the command line.

II. Scripting

a. Scripting on Windows

The advantage of operating the ARSS using command-line arguments is that you can automate some tasks using scripts. On Windows, a script is typically a batch file, that is a text file which name ends with .bat and that contains a series of command prompt commands. You can then just run these series of commands by opening the script, but more importantly, you can drag-and-drop files to be automatically processed. Here's a .bat script example, assuming that you have installed the ARSS in "C:\Program Files\arss\" :

"C:\Program Files\arss\arss" --quiet %1 %1.bmp --analysis --min-freq 27.5 --max-freq 8000 --bpo 48 --pps 150 --brightness 2 --format-param 16
"C:\Program Files\arss\arss" -q %1.bmp --sine -min 55 -b 48 --pps 50 %1_slower_higher.wav -g 2 -sample-rate 44100
del %1.bmp

If you drag-and-drop a WAV file named 'sound.wav' on the script, which in the script is known as %1 (for it is the script's argument #1), the ARSS will analyse it using the provided settings, save it as 'sound.wav.bmp', then it will synthesise this image into a new sound using different parameters. The difference between parameters mean that your new automatically generated sound will play 3 times slower than the original, and 1 octave higher. The last line of the script deletes the intermediate image file.

And that's just a basic example. It gets even better when you use the ARSS along with other programs.

b. Scripting on Linux/Mac OS X/BSD/etc..

Fortunately for every of you out there who do not use Windows, everything we demonstrated above works on any other modern operating system. The syntax is just a bit different, and you have an added advantage : you can fairly easily combine the power of the ARSS with the might of other command-line utilities, particularly image and sound conversion/processing utilities. The ARSS only reads BMPs and you want to turn your collection of JPGs into eerie soundscapes? The ARSS only accepts WAVs and you want to apply some funky effect to your collection of MP3s? Then you might want to look into ImageMagick, SoX, even VLC or better yet LAME. The first one will convert images between the ARSS-friendly BMP and any other format, and the other ones will convert between ARSS's WAV sounds and various sound/video formats.

In the following example we'll use ImageMagick's 'convert' command only to convert image formats, but a look at 'convert -help' will give you a quick idea of the possibilities. In order to run this script you need to paste the code in a text file that we'll call 'arss-script.sh', and then you need to run the command 'chmod 777 arss-script.sh' or equivalent, and you can convert an entire folder of images by running './arss-script.sh *.jpg'

#!/bin/sh
while [ $# -gt 0 ];
do
        convert -type TrueColor -format "BMP" "$1" a.bmp;
        arss -q a.bmp "$1.wav" -min 20 -max 20000 --pps 100 -r 44100 -f 16 --noise;
        rm a.bmp;
        shift;
done;

The 'convert' command will convert one by one each JPG image into a BMP image, and the ARSS will synthesis this 'a.bmp' image into a WAV file named after the original image it is made from. When turning a photograph into a sound it's highly recommended to use noise synthesis rather than sine synthesis. It is however a much slower technique so you might want to use sine synthesis if you're looking for nearly instantaneous results instead.

Note that it is possible to produce an equivalent script for Windows. You just have to install ImageMagick for Windows, and specify the full path to 'convert.exe', as well as the full path to 'arss.exe', and you can then drag-and-drop a group of images onto the .bat script.

@echo off
:loop
        if [%1]==[] goto end
        "C:\Program Files\ImageMagick-6.4.1-Q8\convert.exe" -type TrueColor -format "BMP" %1 a.bmp
        "C:\msys\home\arss\arss" -q a.bmp %1.wav -min 20 -max 20000 --pps 100 -r 44100 -f 16 --noise
        del a.bmp
        shift
goto loop
:end

Note that this is once again a basic example. There are many things you can do from that, like modifying the picture's gamma to make it darker/more contrasted, adjusting the sharpness or trying the wide range of other image effects. The possibilities are vast, if not immense. It is now up to you to explore them.

On a side note, if you're considering turning photographs into sounds, I suggest you to priviledge images with interesting textures, patterns or repetitive features rather than interesting shapes. Clouds, rocks, water, bridges and hair often make up interesting sounds.