How To Get Started!

Step 0: Install The Prerequisities	Make sure ffmpeg and gcc are installed on your system, and in your shell's execution path. To determine if these tools are already installed and available on your system, use the Unix "which" command, like so: If ffmpeg and gcc are installed, the output will look something like the above. If one or the other "which" command produces no output, then the program is either not installed on your system, or it's not in your shell's executable path. If ffmpeg and/or gcc are not found on your system, you'll need to install them. How you do this will depend upon what OS you have. For Linux users, simply use apt-get, or yum, or whatever package manager your particular distribution uses if these tools aren't already installed. If you're a MacOS user, you'll need to install brew first. (Brew is a package manager for Mac OS.) Once brew is installed, use brew to install ffmpeg and gcc. Once they're installed, The "which gcc" and "which ffmpeg" commands should work, and output something similar to the above.
Step 1: Download And Unpack The Hilligoss Encoder Tarball	Click here to download hilligoss-1.1.tar.gz To unpack the archive, issue the command you see below: Unpacking the archive will create a new folder/subdirectory called "hilligoss-1.1".. There, you'll find the source code, some wrapper scripts to make life easier for yourself (process.sh and processall.sh) and a small little 30 second MPEG you can use to test out Hilligoss with.
Step 2: Compile Hilligoss	Issue the commands you see below to go into the newly created folder/subdirectory, and compile Hilligoss 1.1.. What you see on your system should look very similar to this: When gcc runs, it shouldn't produce any output if everything's correct. That being said, you may see a compiler warning, but this should be ignorable. The compiler should spit out a binary, ready-made for your particular system, and ready to run. You can use the "ls" command to see the results:
Step 3: Test It Out!	You're basically ready to go at this point! Inside that folder/subdirectory, you might have noticed a little video file called "galleria.mp4". Before we run Hilligoss for the first time, let's make our window a bit wider (at least 125 columns or so) and test Hilligoss, using the command below: ./processall.sh galleria.mp4 The output should look similar to this: "processall.sh" is a wrapper script that intelligently manages the process of slicing up a video into individual frames, and then spawning a number of concurrent Hilligoss threads to attack the encoding process in parallel. Once all the work of converting all the frames to vector data has completed, all the individual sound files that Hilligoss creates will be reassembled into one singular .wav file. The name of this file (and its size) will be shown at the end of the encoding process. This is the resulting .wav file you can play using Osci-Render, Sosci, or played directly against the hardware oscilloscope of your choice.
Step 4: Relax, Enjoy, And Tweak	Hilligoss is an extremely tweakable tool, and part of the fun of it is throwing goofy parameters at it, and fine-tuning the values to optimize image quality. The encoder will do its best to prevent you from doing anything nonsensical, but there's still plenty of flexibility there, and plenty of room for experimentation. The runtime arguments for Hilligoss are stored inside the process.sh file. The Hilligoss encoder obeys the following parameters: -b {black threshold, 0-255} This value tells the encoder that any pixels below this value {out of 255} should be considered completely black, and therefore ignored during the encoding process. -w {white threshold, 0-255} Similarly, this argument tells the encoder that any pixels brighter than this amount should be considered absolutely white, and therefore a strong candidate for inclusion. Feel free to tweak these values to taste. -c {vector count, 0-262144} The encoder needs to know how many vector points it has to work with, when representing a bitmap image. The larger the number of points, generally the better the image quality, but there's a somewhat of a trade-off here. For example, if your sound file is 48 KHz, then 2000 vector points per frame will equate with 24 FPS {2000 * 24 = 48000}. -x {preview width/columns} Hilligoss will render a lovely ASCII-art preview of the image, and the resulting vector points. This value controls how wide the preview window is. -y {preview height/rows} Similarly, this value controls the preview window height. -j {jump frequency 0-262144} This value controls how frequently Hilligoss will randomly jump to a new point in the image. This is a useful value to control in the event an image has a large number of "islands" of pixels. If this value is too low, those islands will be ignored. If this value is too high, the overall image will be too fuzzy. Adjust to taste.