Add how_it_works.

1 files changed, 99 insertions, 0 deletions

diff --git a/how_it_works.md b/how_it_works.md
new file mode 100644
index 0000000..606ecdf
--- /dev/null
+++ b/how_it_works.md
@@ -0,0 +1,99 @@
+Reminder that this is all just rough for now.  Also I squeezed it all
+into one file to make things easy to try out, no need to put things in
+your path or for it to know where you installed it.  Later, when it
+becomes a proper package, things will be split up and spread around
+properly.
+
+Note that everything is subject to change without notice, this being a
+very raw project for now.
+
+aataaj.lua is a polyglot script, written in such a way that several
+different things can deal with it, including shell and Lua languages.
+
+The very first line is your typical shell script first line, but telling
+the system that it's Lua not shell script.  Perl and Python do similar
+things, and there is likely plenty of those scattered around your system,
+other languages to.  Lua basically ignores the first line if it starts
+with #.  The system that runs files checks the beginning of the file to
+see how it should run.  Binaries have magic numbers, scripts have this #!
+thing.  So that system only reads that first line, then passes the script
+to that command in the first line.
+
+The next bit of palyglotism is the Sys V LSB comment block.  This is the
+magic that turns it into an init script you can put in /etc/init.d  Any
+LSB compliant init program will look for a comment block like that near
+the beginning of the script.  This is why all the scripts in /etc/init.d
+have such a thing near the top.  In this case the script type comment
+block is wrapped inside a Lua comment block.  Lua will ignore it,  Shell
+interpreters will ignore it, but shouldn't even get this far anyway.  LSB
+compliant init programs will find what they are looking for.
+
+This tells the system to run it in run level S for Start, and before
+alsa-utils and espeakup.  So should in theory be the first thing to mess
+with ALSA other than the kernel.
+
+
+The next major blob of stuff in aataaj.lua is the Help text, which is a
+copy of README.md.  Later the --help option will print README.md instead
+of having it's own copy.
+
+The definition of APT is something I just copied from my apt-panopticon
+project.  Should break it out into it's own separate library some day.
+
+Then comes the argument handling.  Handles the usual init script
+arguments, plus a couple more.  Some are just aliases for "start", for
+now.
+
+"stop" is very crude and violent, mostly just killall.
+
+
+A short bit where you can change some options.
+
+
+The actual audio device scanning.
+
+Basically we scan through /proc/asound/card[0-9]* looking for audio
+devices that the kernel has already recognised.  Collect a few details
+about what we find, stuff it in the Cards table.  For playback devices we
+feed some of those details into espeak-ng, so it'll speak them through
+this found playback device.  If this is running during init startup time,
+then the computer should speak through all audio output devices one at a
+time, and you should hear it through anything with speakers attached.
+
+
+If this is "start" then it'll write details about what it found into
+/var/lib/aataaj/ files.  One is a jack-plumbing config file for the later
+JACK stage, the other is a fragment of an ALSA / asound config file you
+can include in the real ones.  This includes some extra stuff that is
+experiments to get ALSA and JACK to behave that are commented out.
+
+
+If this is "JACK" then it'll start up a bunch of JACK software, and hook
+everything up in JACK.
+
+First it starts the JACK server, then starts up a patchbay GUI so you can
+watch the rest of what happens.
+
+Next up is jack-plumbing, using that config file we created before.  This
+automates the various connections we are about to make.  Note this config
+is only used for this setup phase, you can still use your own
+jack-plumbing config.
+
+a2jmidid is up next, which is used to automatically connect MIDI devices
+into the JACK system.  Alas the same thing doesn't happen with audio
+devices, which is why I need this script.
+
+Next we use alsa_in / alsa_out and their zita equivalents to create JACK
+devices for all those ALSA devices we found.  We start with anything
+configured in the alias table, then add the ALSA loopback devices. 
+Finally we loop through what's left.  Since jack-plumbing is running with
+our generated config, it'll automatically hook everything up to
+everything else.
+
+Next we scan for joysticks, and use aseqjoy to convert them into MIDI
+input devices.  Just coz.  B-)
+
+Next we fire up qsynth, so you have something to play that makes noises.
+
+Finally we wait for a bit, then kill the jack-plumbing we started.  It's
+done it's job, the user can pick their own session management.