docs: update README.md

README.md

@@ -7,19 +7,19 @@ intros, forked from [4klang](https://github.com/hzdgopher/4klang). Targetable
 architectures include 386, amd64, and WebAssembly; targetable platforms include
 Windows, Mac, Linux (and related) + browser.
 
-The user manual is available in the
+- [User manual](https://github.com/vsariola/sointu/wiki) is in the Wiki
-[Wiki](https://github.com/vsariola/sointu/wiki). You can ask for help in the
+- [Discussions](https://github.com/vsariola/sointu/discussions) is for asking
-[Discussions](https://github.com/vsariola/sointu/discussions) or from pestis_bc
+  help, sharing patches/instruments and brainstorming ideas
-on the Demoscene Discord.
+- [Issues](https://github.com/vsariola/sointu/issues) is for reporting bugs
 
 Installation
 ------------
 
-You can either 1) download the prebuilt release binaries from the
+You can either 1) download the latest build from the master branch from the
-[releases](https://github.com/vsariola/sointu/releases); or 2) download the
-latest build from the master branch from the
 [actions](https://github.com/vsariola/sointu/actions) (find workflow "Binaries"
-and scroll down for .zip files containing the artifacts). Then just run one of
+and scroll down for .zip files containing the artifacts); or 2) download the
+prebuilt release binaries from the
+[releases](https://github.com/vsariola/sointu/releases). Then just run one of
 the executables or, in the case of the VST plugins library files, copy them
 wherever you keep you VST2 plugins.
 
@@ -76,7 +76,8 @@ for the audio, so the portability is currently limited by these.
 #### Prerequisites
 
 - [go](https://golang.org/)
-- If you want to use the faster x86 assembly written synthesizer:
+- If you want to use the x86 assembly written synthesizer, to test that the
+  patch also works once compiled:
    - Follow the instructions to build the [x86 native virtual machine](#native-virtual-machine)
      before building the tracker.
    - cgo compatible compiler e.g. [gcc](https://gcc.gnu.org/). On
@@ -126,7 +127,7 @@ a dynamically linked library and ran inside a VST host.
   if it is not set and go fails to find the compiler, go just excludes
   all files with `import "C"` from the build, resulting in lots of
   errors about missing types.
-- If you want to use the faster x86 assembly written synthesizer:
+- If you want to use the x86 assembly written synthesizer:
    - Follow the instructions to build the [x86 native virtual machine](#native-virtual-machine)
      before building the plugin itself
 
@@ -330,7 +331,7 @@ New features since fork
     `text/template` package, effectively working as a preprocessor. This allows
     quite powerful combination: we can handcraft the assembly code to keep the
     entropy as low as possible, yet we can call arbitrary go functions as
-    "macros". The templates are [here](templates/) and the compiler lives
+    "macros". The templates are [here](vm/compiler/templates/) and the compiler lives
     [here](vm/compiler/).
   - **Tracker**. Written in go. Can run either as a stand-alone app or a vsti
     plugin.
@@ -347,9 +348,9 @@ New features since fork
     opcodes. So, you can have a single instrument with three voices, and three
     tracks that use this instrument, to make chords. See
     [here](tests/test_chords.yml) for an example and
-    [here](templates/amd64-386/patch.asm) for the implementation. The maximum
+    [here](vm/compiler/templates/amd64-386/patch.asm) for the implementation.
-    total number of voices is 32: you can have 32 monophonic instruments or any
+    The maximum total number of voices is 32: you can have 32 monophonic
-    combination of polyphonic instruments adding up to 32.
+    instruments or any combination of polyphonic instruments adding up to 32.
   - **Any number of voices per track**. A single track can trigger more than one
     voice. At every note, a new voice from the assigned voices is triggered and
     the previous released. Combined with the previous, you can have a single
@@ -358,13 +359,13 @@ New features since fork
     Not only that, a track can even trigger voices of different instruments,
     alternating between these two; maybe useful for example as an easy way to
     alternate between an open and a closed hihat.
-  - **Easily extensible**. Instead of %ifdef hell, the primary extension
+  - **Reasonably easily extensible**. Instead of %ifdef hell, the primary
-    mechanism is through new opcodes for the virtual machine. Only the opcodes
+    extension mechanism is through new opcodes for the virtual machine. Only the
-    actually used in a song are compiled into the virtual machine. The goal is
+    opcodes actually used in a song are compiled into the virtual machine. The
-    to try to write the code so that if two similar opcodes are used, the common
+    goal is to try to write the code so that if two similar opcodes are used,
-    code in both is reused by moving it to a function. Macro and linker magic
+    the common code in both is reused by moving it to a function. Macro and
-    ensure that also helper functions are only compiled in if they are actually
+    linker magic ensure that also helper functions are only compiled in if they
-    used.
+    are actually used.
   - **Songs are YAML files**. These markup files are simple data files,
     describing the tracks, patterns and patch structure (see
     [here](tests/test_oscillat_trisaw.yml) for an example). The sointu-compile
@@ -419,36 +420,9 @@ New features since fork
     releasing voices etc.)
   - **Calling Sointu as a library from Go language**. The Go API is slighty more
     sane than the low-level library API, offering more Go-like experience.
-  - **A bytecode interpreter written in pure go**. It's slightly slower than the
+  - **A bytecode interpreter written in pure go**. With the latest Go compiler,
-    hand-written assembly code by sointu compiler, but with this, the tracker is
+    it's slightly faster hand-written one using x87 opcodes. With this, the
-    ultraportable and does not need cgo calls.
+    tracker is ultraportable and does not need cgo calls.
-
-Future goals
-------------
-
-  - **Find a more general solution for skipping opcodes / early outs**. It might
-    be a new opcode "skip" that skips from the opcode to the next out in case
-    the signal entering skip and the signal leaving out are both close to zero.
-    Need to investigate the best way to implement this.
-  - **Even more opcodes**. Some potentially useful additions could be:
-    - Equalizer / more flexible filters
-    - Very slow filters (~ DC-offset removal). Can be implemented using a single
-      bit flag in the existing filter
-    - Arbitrary envelopes; for easier automation.
-  - **MIDI support for the tracker**.
-  - **Find a solution for denormalized signals**. Denormalized floating point
-    numbers (floating point numbers that are very very small) can result in 100x
-    CPU slow down. We got hit by this already: the damp filters in delay units
-    were denormalizing, resulting in the synth being unusable in real time. Need
-    to investigate a) where denormalization can happen; b) how to prevent it:
-    add & substract value; c) make this optional to the user. For quick
-    explanation about the potential massive CPU hit, see
-    https://stackoverflow.com/questions/36781881/why-denormalized-floats-are-so-much-slower-than-other-floats-from-hardware-arch
-
-Long-shot ideas
------------
-  - **Hack deeper into audio sources from the OS**. Speech synthesis, I'm eyeing
-    at you.
 
 Design philosophy
 -----------------
@@ -470,8 +444,8 @@ Design philosophy
   - Benchmark optimizations. Compression results are sometimes slightly
     nonintuitive so alternative implementations should always be benchmarked
     e.g. by compiling and linking a real-world song with
-    [Leviathan](https://github.com/armak/Leviathan-2.0) and observing how the
+    [one of the examples](examples/code/C) and observing how the optimizations
-    optimizations affect the byte size.
+    affect the byte size.
 
 Background and history
 ----------------------
@@ -525,6 +499,7 @@ Prods using Sointu
   - [Bicolor Challenge](https://demozoo.org/competitions/19410/) with [Sointu
     song](https://files.scene.org/view/parties/2024/deadline24/bicolor_challenge/wayfinder_-_bicolor_soundtrack.zip)
     provided by wayfinder
+  - [napolnitel](https://www.pouet.net/prod.php?which=104336) by jetlag
 
 Contributing
 ------------