update README

Signed-off-by: James Calligeros <jcalligeros99@gmail.com>

README.md

@@ -1,24 +1,61 @@
-## Asahi Linux speaker safety daemon
+## speakersafetyd - a software Smart Amp implementation
+speakersafetyd is a userspace daemon written in Rust that implements an
+analogue of the Texas Instruments Smart Amp speaker protection model.
 
-## IMPORTANT
+Apple Silicon Macs mostly use the Texas Instruments TAS2764 amp chip (codec
-This software is still pre-release and not fit for use or testing on user machines. Please
+in ALSA parlance), which provides sense lines for the voltage and current across
-do not ask for help with installing or using this software, the Pipewire configuration,
+the voice coil of the connected speaker. These codecs are designed to be used
-or enabling speaker output on your machine. An announcement will be made when speaker
+in embedded applications where device firmware takes this information and uses
-support is ready for use.
+it to protect the speaker from damage. Apple instead implement this as machine-specific
+plugins to the userspace half of CoreAudio. An increasing number of other
+vendors in both the desktop and embedded/Android worlds are choosing to go down a similar
+route, folding this functionality into proprietary driver/userspace blobs that usually
+also bundle niceties like EQ (we have a solution for this too, see [asahi-audio](https://github.com/AsahiLinux/asahi-audio)).
+This puts users at serious risk of permanently destroying their expensive devices if they choose
+to run custom software, such as Asahi Linux or an Open Source Android ROM.
 
-## Requirements
+speakersafetyd is the first (as far as we know) FOSS implementation of a speaker
-* A patched eleven secret herbs and spices kernel
+protection model. It solves the problem described above by allowing parties interested
+in compatible devices to quickly and easily implement a speaker protection model for those
+devices. Only Apple Silicon Macs under Linux are currently supported,
+however the model applies to all loudspeakers. The daemon itself should be easy enough to
+adapt for any device that provides V/ISENSE data in a manner similar to TAS2764.
 
-## Todo list
+### Dependencies
-- [x] Data structures representing a speaker element
+* Rust stable
-- [x] Parsing machine-specific values from a config file
+* alsa-lib
-- [x] Logging
+* An Apple Silicon Mac running Asahi Linux
-- [x] Mixer control data structures
+
-- [x] Manipulating mixer controls
+### Some background on Smart Amps
-- [x] Retrieving V/ISENSE values
+The cheap component speaker elements used in modern devices like
-- [x] Model of voice coil/magnet temperatures
+Bluetooth speakers, TVs, laptops, etc. are very fragile. In order
-- [x] Ramping volume according to safety model
+to eke the highest possible sound quality out of them, they need to be
-- [x] Tolerate multiple sample rates
+driven *hard*. This leaves us with a dilemma - how do we drive these
-- [x] Sleep reliably while playback has stopped
+speakers hard enoguh to get a loud, high-quality output but not hard
-- [x] Kernel driver interlock
+enough to destroy them?
-- [ ] Packaging/distro-agnosticism
+
+A speaker's electromechanical characteristics can be modelled
+and boiled down to a set of parameters - the Thiele/Small Parameters.
+These can be used to predict what the speaker will do with certain
+inputs. When we add measured properties like the time constant of
+the speaker's voice coil's and magnet's temperature curve, we can
+accurately model a speaker's temperature for any given voltage/current
+across the coil. When the speaker is getting too hot, we just reduce the
+power going to it until it cools down.
+
+This lets us fearlessly drive the speakers as hard as they physically can
+be without being permanently damaged. This is extremely useful, as without it
+the output level on these devices would have to be hard limited to a very low
+level that is known to be safe for the worst possible input. Instead, we can
+simply duck the output in those cases and allow the speakers to oeprate at
+full power where possible.
+
+Many integrated amplifier chips implement this functionality in hardware, as well
+as additional advanced DSP features like compressors and limiters. Texas Instruments
+call their implementation "Smart Amp." Integrators need only communicate the parameter set
+to the chip for the speaker it is connected to, and it does the rest. Many do not however,
+and instead only provide facilities for measuring the voltage and current across the speaker's
+voice coil. It is up to the implementer to capture this data and do something with it.
+
+speakersafetyd is (as far as we know) the first and only FOSS implementation of the
+Smart Amp protection model.