Updated readme

README.md

@@ -10,7 +10,36 @@ Recently I got back into messing with chip tunes on the venerable BBC Micro just
 
 Turns out that wasn't such a crazy idea because the Atari ST uses a PSG that's pretty similar to the Beeb.
 
-This repo contains some scripts I've hacked together to do the conversion.
+This repo contains a script I've created to do the conversion so that you can listen to these tunes on an SN76489 sound chip as well.
+
+## Usage
+
+```
+ym2sn.py : Convert Atari ST .YM files to SN76489 VGM music files
+Written in 2019 by Simon Morris, https://github.com/simondotm/ym2149f
+
+usage: ym2sn.py [-h] [-o <output>] [-v] input
+
+positional arguments:
+  input                 YM source file (must be extracted from within the
+                        original YM file) [input]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -o <output>, --output <output>
+                        write VGM file <output> (default is '[input].vgm')
+  -v, --verbose         Enable verbose mode
+
+```
+
+
+Notes:
+
+* YM files are actually LHA compressed archives which contain a single file (usually also called .YM or .BIN)
+* This tool only works with the uncompressed inner YM file (as there are no Python LHA decoders I could find or easily install)
+* Therefore it is necessary to manually extract the inner YM file to feed to this script (using 7zip or similar archive tool)
+
+
 
 ## How it works
 
@@ -77,7 +106,7 @@ The basic conversion process is as follows:
 1. Scan through the YM file, one 50Hz frame at a time
 1. Convert as best as possible the register updates going to the YM chip in each frame to an equivalent 'best fit' register set update for the SN chip
 1. Map the 4-bit output levels directly for each channel from YM -> SN
-1. _Ignore hardware envelopes (for now)_
+1. Simulate the hardware envelopes, and apply attenuation as best we can* _(see below)_
 1. If tone frequencies are too low for the SN chip, map them to 'periodic noise' on the SN chip (typically bass lines), but give drum/noise sounds priority 
 1. If tone frequencies are still too high or too low for the SN chip, bring them back into range an octave at a time
 1. Where noise mixer is enabled, emulate this mix by computing aggregate volume for the SN noise channel across the 3 YM mixers -> 1 SN noise output
@@ -91,12 +120,24 @@ See Bitshifters' [Twisted Brain Demo](https://bitshifters.github.io/posts/prods/
 
 
 ## Challenges
+### Frequency Range
+The SN76489 frequency range is determined by its clock speed, and for higher clocked systems (such as the BBC Micro at 4Mhz) it is not possible to reproduce lower frequencies. The script does its best to simulate these using periodic noise where appropriate, however a more accurate render can be generated by setting a lower SN clock speed.
+
 ### Envelopes
 Quite a lot of Atari ST tunes don't really use the envelope feature much, which makes conversions of these tunes a bit easier. 
 
 However, the tunes that do use them, have a much different tonal landscape and sound pretty bad (harsh) when ported to the SN. 
 
-That said, envelopes can _I feel_ be emulated on an SN chip, as they are simple modulators of the volume for each tone generator, but supporting them will require much more CPU time in a hardware player, since some of the envelopes in some tunes require updates at reasonably high frequencies - ie. upto tens of kilohertz. 
+That said, envelopes can be emulated as they are simple modulations of the volume for each tone generator. 
+
+#### Envelope Emulation
+This script supports emulation of the YM2149 envelope generator hardware, however it samples the current envelope output level at a default frequency of 50Hz, which means they are _highly approximated_, however even a simple approximation means that the output tune sounds much better than without any envelope consideration at all.
+
+#### Envelope Sample Rate
+There are routines implemented in the script that enable a higher sampling rate of the envelopes (for more accurate audio rendering), but be warned - they will generate very large VGM files, since the sound chip volumes need to be updated at a much higher frequency to allow for the high frequencies of the envelope modulator. There is further work to do on this feature, as the volumes are not filtered very accurately at the moment, so there's a lot of aliasing.
+
+#### Envelope CPU emulation
+In theory, envelopes could be supported CPU side, however supporting them will require a lot of CPU time in a chip tune player, since some of the envelopes in some tunes require updates at reasonably high frequencies - ie. upto tens of kilohertz. 
 
 ### Noise mixer
 Some tunes use quite subtle combinations of the 3 noise mixers, which are very tricky if not impossible to 'fully' emulate on an SN chip, but when converted using a mixed approach, they don't sound too far off. Also worth noting that the YM and SN chips use different pseudo-white-noise generators so that changes tonal effect too.