new docs

README.md

@@ -1,3 +1,26 @@
-For documentation, visit https://www.blendermarket.com/products/audvis/docs
+# Blender AudVis
+
+AudVis is a Blender 2.8 and higher add-on helping you to build awesome audio visualizations. The main features are Real Time Analyzer and Sequence Analyzer.
+
+For original documentation, visit https://www.blendermarket.com/products/audvis/docs
 
 For download, visit https://github.com/example-sk/audvis/releases
+
+* [Installing python packages](doc/packages-install.md)
+* Analyzers:
+    - [Sequence Analyzer](doc/sequence.md)
+    - [Realtime Analyzer](doc/realtime.md)
+    - [MIDI File](doc/midi-file.md)
+    - [MIDI Realtime](doc/midi-realtime.md)
+* [Driver Values](doc/driver-values.md)
+* How to animate things:
+    - [Using drivers](doc/drivers.md)
+    - [Shape Modifier](doc/shape-modifier.md)
+    - [Generate Armature](doc/armature.md)
+    - [Generate Example Objects](doc/example-objects.md)
+    - [Scripting](doc/scripting.md)
+* [Spectrogram](doc/spectrogram.md)
+* [Video Capture](doc/video-capture.md)
+* [Bake Drivers](doc/bake-drivers.md)
+* [Spread the Drivers](doc/spread-the-drivers.md)
+* [UPBGE](doc/upbge.md)

doc/armature.md

@@ -0,0 +1,23 @@
+# Armature Generator
+
+This feature gets **selected** faces of your **mesh** object, and creates a new armature object + a new Armature
+modifier on the original mesh object. All the created bones will be animated along the face's normal, thus move the face
+along its normal. This is done by creating a driver for the location Y for every single created bone. With default
+settings, one of the bones will have a driver expression like this `audvis(450.0, 500.0) * 0.1`
+
+Video: [![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/e0v9dO3wU1s/0.jpg)](https://www.youtube.com/watch?v=e0v9dO3wU1s)
+
+## Settings:
+
+- **Inset** - performs also "Inset Faces" on all the selected faces. Only the new created faces will be animated.
+    - **Extrude After Inset** - after "Inset Faces", also "Extrude" will be performed. Only the new faces after
+      extruding will be animated
+    - **Inset Size** - this is the same like "Thickness" property of the "Inset Faces" operator.
+- **Multiple Freq properties** - the whole concept is [described here](./freq-sequencing.md)
+- **Keep Old Vertex Groups**
+    - if disabled, for every clicking on Generate AudVis Armature, AudVis will delete all the vertex groups with names
+      starting with AudvisArm
+    - if enabled, only new vertex groups will be created, so you can use the same armature, but add new animated bones.
+      In this case, don't forget to set **Frequency Start**
+- **Generate AudVis Armature** - perform the generating process. Please, always save your project before doing this, so
+  you can easily return to previous state in case you don't like the result. Mainly if using Inset and Extrude.

doc/bake-drivers.md

@@ -0,0 +1,11 @@
+# Bake Drivers
+
+Finds all the drivers using audvis() expressions everywhere and bakes them into classical animation data, so you can
+render your animation on a render farm or on a PC without AudVis installed.
+
+## Settings
+
+- **Bake Drivers** - start baking all the drivers. You can stop it by pressing Esc
+- **Nonstop Baking Collection** - if a collection is selected, baking will be performed on the go, as YOU move along the
+  frames. If you jump to frame 143, data will be baked to the frame 143. This can be changed in the future.
+- **Edit Driver Expressions Here** only if **Nonstop Baking Collection** is selected. If enabled, you will see a list of all driver expressions in the selected collection

doc/driver-values.md

@@ -0,0 +1,26 @@
+# Driver Values panel
+
+[Realtime](./realtime.md) and [Sequence](./sequence.md) analyzers produce data. In Driver Values you can tweak them.
+
+## Settings:
+
+- if **Use Better Filters** is disabled (default):
+    - **Highpass Frequency** and **Highpass Strength** - a
+- if **Use Better Filters** is enabled:
+    - before FFT is performed, current sound chunk data is loaded into `aud.Sound` object and then these things are
+      applied:
+    - **Highpass Frequency** and **Q** - [highpass](https://docs.blender.org/api/current/aud.html#aud.Sound.highpass)
+    - **Lowpass Frequency** and **Q** - [lowpass](https://docs.blender.org/api/current/aud.html#aud.Sound.lowpass)
+    - **Attack, Decay, Sustain, Release** - [ADSR](https://docs.blender.org/api/current/aud.html#aud.Sound.ADSR)
+    - **Use Curve** - if enabled, you can make your own highpass and lowpass filter - left part of the curve is for
+      lower frequencies, right part of the curve is for highest frequencies
+- **Factor** - all values will be multiplied by this value
+- **Max** - doesn't allow values higher than this
+- **Add** - adds this number to all calculated values
+- **Add Noise** - adds
+- **Normalize Values** - just try it, I don't know
+- **Fade Out Type**:
+    - **Off** - don't fade out
+    - **Linear** - returns higher value of "previous frame value - **Fade Out Speed**" or "current value"
+    - **Exponential** - returns higher value of "previous frame value * (1 - **Fade Out Speed**)" or "current value"
+    - warning: if you jump between frames, the results can be inconsistent

doc/drivers.md

@@ -0,0 +1,51 @@
+# Drivers
+
+You can animate many, many things by writing your own drivers. Just right click on any numeric value, for example
+object's Location X, and click "Add Driver". Then write any expression.
+
+Simplest formula looks like this: `audvis(100, 200)` - this will animate your property by sound frequencies 100Hz -
+200Hz.
+
+## Python driver expressions
+
+You want to read the manual [here](https://docs.blender.org/manual/en/latest/animation/drivers/drivers_panel.html),
+[here](https://docs.blender.org/manual/en/latest/animation/drivers/introduction.html)
+and [especially here](https://docs.blender.org/manual/en/latest/animation/drivers/drivers_panel.html#drivers-simple-expressions)
+.
+
+Here are some simple expressions to show what you probably want to do:
+
+- `audvis(100, 200) * 10 + 100`
+- `3 - audvis(100, 200) / 15`
+- `clamp(audvis(100, 200) / 3, 0, 3)`
+
+## Expressions for Realtime and Sequence analyzers:
+
+- **seq** - `audvis(100, 200, seq="MyGreatSong.mp3")` - only react to MyGreatSong.mp3
+- **ch** - `audvis(100, 200, ch=2)` - channel. By default, only one channel is parsed, so if you want to use more of
+  them, you need to increase the value of `Channels Count` property in the main AudVis panel
+- **seq** and **ch** can be combined - `audvis(100, 200, seq="MyGreatSong.mp3", ch=2)`
+
+## Expressions for MIDI File and MIDI Realtime analyzers:
+
+- **midi** - `audvis(midi=1)` - note 1. This parameters is needed if you want to use any midi
+- **device** - `audvis(midi=1, device="MIDI Device 1")` - name of the device from the MIDI Realtime panel
+- **ch** - `audvis(midi=1, ch="1")` - midi channel
+- **file** - `audvis(midi=3, file='MyGreatSong.mid')` - file name from the MIDI File panel
+- **track** - `audvis(midi=3, file='MyGreatSong.mid', track='Track 1')` - track from the file. If your tracks in the
+  MIDI are not named, they will get names like "Track 1"
+- you can combine **device** + **ch**, or **file** + **track** + **ch**, but **device** + **file** makes absolutely no
+  sense.
+
+## Some ideas what to animate with drivers:
+
+- object's basic properties like location, rotation, scale
+- shape key value
+- array modifier's Count property
+- `Object -> Viewport Display -> Color` and use it inside shading nodes`
+- armature bones' properties - rotation and/or scale or event Bone Constraints
+- light color / power / radius...
+- camera focal length
+- almost any nodes in geometry nodes, shading, compositing...
+- depth of field settings
+- just experiment! Explore all the possibilities (impossible) and have fun

doc/example-objects.md

@@ -0,0 +1 @@
+## TODO

doc/freq-sequencing.md

@@ -0,0 +1,32 @@
+# Concept: Frequency Sequencing
+
+[Shape Modifier](./shape-modifier.md), [Spectrogram](./spectrogram.md), [Generate Example Objects](./example-objects.md)
+, [Generate Armature](./armature.md) use the same concept. AudVis iterates over a list of points/bones/objects and moves
+them somehow. Here is explanation.
+
+For simplicity, word "point" is used here, but it means vertex, face, object, bone or whatever is correct in the
+context.
+
+## Settings
+
+- **Freq Sequencing**
+    - **Linear**
+        - **Frequency Range Per Point** - if set to 50, every item will be animated by range of 50Hz. For example first
+          point will be animated by 0-50Hz, second one (according to other settings) 50-100Hz or 10-60Hz... and so on
+        - **Frequency Start** - how many Hz to skip. If set to 200, first point will be animated for example by
+          200-250Hz
+        - **Set Custom Step** and **Frequency Step**
+            - if disabled, the sequence will be 0-50Hz, 50-100Hz, 100-150Hz...
+            - if enabled and the Step set to 10, the sequence will be: 0-50Hz, 10-60Hz, 20-70Hz...
+    - **Notes** - [wiki](https://en.wikipedia.org/wiki/Piano_key_frequencies)
+        - **A4 Note Frequency** - default 440Hz, but you can set it to whatever you want
+        - **Note Step** - if you have a lot of points to animate, you probably want to lower this number. If not, keep
+          it on 1.0
+        - **Note Step Offset** - on what note you want to start - affected by **Note Step**. If you have a lot of bass,
+          you probably want to use negative values for this property
+    - **MIDI Notes** - every point is 1 midi note
+        - **MIDI Note Offset** - if you are interested only in notes higher than 40, set this property to 40
+    - There is also one line telling you what sequences you will get in your animation. For example 0.00 - 4,150.00 Hz.
+      If you see too high numbers here, for example over 20 000 Hz, you want to change your settings to get lower
+      number. If your sound input's sampling frequency is 44100 Hz, FFT used by AudVis can't give you numbers over
+      22050Hz (sampling frequency / 2). 

doc/midi-file.md

@@ -0,0 +1,20 @@
+# MIDI File
+
+If you want to animate things by MIDI File, this is what you are searching for. AudVis will read the file using Python
+module mido, and save the parsed data into animation data.
+
+## Settings
+
+- **Enable** (in the Midi File panel header): do you want to use Midi File feature? If not, keep this disabled
+- **Enable** single midi file - you can enable/disable every single midi file for use in AudVis
+- **Add Midi File** - choose a midi file to use. You can use multiple midi files, and animate different things by
+  different midi files
+- **Remove Midi File** - remove selected midi file
+- **Name** - internal name of the midi file. You can change it or copy the name to use it in the [driver](./drivers.md)
+  expression
+- **Frame Start** - frame when to start using this midi file
+- **Hold Offset Start** - just offset - you can cut out the start of the song for example
+- **Hold Offset End** - just offset - you can cut out the end of the song for example
+- **Tracks** - list of tracks inside selected file
+- **Track Name** - You can change it or copy the name to use it in the [driver](./drivers.md) expression
+- **Remove Midi Track** - you can remove single track from a midi file (this doesn't affect the MIDI file on the disk) 

doc/midi-realtime.md

@@ -0,0 +1 @@
+## TODO

doc/packages-install.md

@@ -0,0 +1,53 @@
+# Installing Python Packages
+
+If you want to use [Realtime Analyzer](./realtime.md), 
+[MIDI File](./midi-file.md), [MIDI Realtime](./midi-realtime.md)
+or [Video Capture](./video-capture.md), you need to install python
+packages. Everything should be done only by clicking on button 
+"Install python packages" under any of mentioned panels. After clicking
+on this button, a new window opens with installation log. If everything
+works fine, you should see something like this:
+
+```
+"""
+RUN /opt/blender/3.1/3.1/python/bin/python3.9 -m ensurepip --altinstall --user
+
+info 2.8s: Looking in links: /tmp/tmpikxtby4l
+info 2.8s: Requirement already satisfied: setuptools in ./.local/lib/python3.9/site-packages (49.2.1)
+info 2.8s: Processing /tmp/tmpikxtby4l/pip-21.2.3-py3-none-any.whl
+info 2.9s: Installing collected packages: pip
+info 4.3s: Successfully installed pip-21.2.3
+
+... (more lines) ...
+
+RUN /opt/blender/3.1/3.1/python/bin/python3.9 -m pip install --force-reinstall --upgrade --target /home/r/.config/blender/3.1/scripts/addons/modules/_audvis_modules/a_1639510547 --no-deps opencv-python
+
+info 1.8s: Collecting opencv-python
+info 1.9s:   Downloading opencv_python-4.5.4.60-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (60.3 MB)
+info 8.4s: Installing collected packages: opencv-python
+info 9.9s: Successfully installed opencv-python-4.5.4.60
+
+
+FINISHED!
+
+
+"""
+```
+
+## Troubleshooting:
+
+If you see errors in the log, you can go to `Edit -> Preferences -> Add-ons -> AudVis`
+and change the "Install directory" to "Blender" instead of default
+"User Add-On Modules", and click on (Re)Install button.
+
+### Windows:
+- You may need to install [Microsoft Visual C++ 2015 Redistributable Update 3 RC.](https://www.microsoft.com/en-us/download/details.aspx?id=52685)
+- Try running Blender as Administrator, and press install button again. ([how to run a program as administrator](https://www.youtube.com/watch?v=nNVdaJXYCbA))
+- If you want to use Realtime Analyzer, setup Stereo Mix ([video instructions here](https://youtu.be/Bd3moKLV5sE))
+
+### Linux:
+- You may need to install libportaudio2 (on debian or ubuntu, the command is `sudo apt-get install libportaudio2`).
+
+### MacOs:
+- Mac computers come with different processor types. Only tested with MacBook Air mid 2012. It would be nice if you test this on other hardware and let me know if it worked.
+- For Realtime Analyzer, you may need to install Soundflower or similar software ([video instructions here](https://www.youtube.com/results?search_query=soundflower+macos).

doc/realtime.md

@@ -0,0 +1,22 @@
+# Realtime Analyzer
+
+Read first: [Installing Python Packages](./packages-install.md)
+
+Realtime Analyzer is the first part of AudVis and the reason, why this whole project has started.
+
+AudVis reads data from your microphone or sound capture using Python package `sounddevice`. Most of the setup is usually
+done outside of Blender and AudVis. You need to setup your operating system settings, setup `Stereo Mix`. It can be
+sometimes frustrating and sometimes if you have some exotic hardware combinations, it can be almost impossible to make
+everything work. You have been warned.
+
+If everything works, [Fast Fourier Transform](https://en.wikipedia.org/wiki/Fast_Fourier_transform) is performed for
+every frame of Blender scene. This means you need to play animation to watch any animation. The result of FFT is stored
+and then used when needed, for example by [drivers](./drivers.md), [Shape modifier](./shape-modifier.md)
+or [Spectrogram](./spectrogram.md).
+
+## Settings:
+
+- **Enable** (in the Realtime Analyzer panel header): do you want to use Real Time Analyzer? If not, keep this disabled
+- **Input Device**: choose the device you want to "listen"
+- **Auto Switch Scenes**: if you have multiple scenes, they will alternate. Please, don't use scenes with too small
+  number of frames

doc/scripting.md

@@ -0,0 +1 @@
+## TODO

doc/sequence.md

@@ -0,0 +1,20 @@
+# Sequence Analyzer
+
+Sequence analyzer is similar to [Realtime Analyzer](./realtime.md), but uses sound sequences in Blender's Video Sequence
+Editor. Don't worry if you don't like the VSE, there is a quite good user interface inside AudVis "Sequence Analyzer"
+panel.
+
+## Settings
+
+- **Enable** (in the Sequence Analyzer panel header): do you want to use Sequence Analyzer? If not, keep this disabled
+- **Enable** single sequence - you can enable/disable every single sound sequence for use in AudVis Sequence Analyzer
+- **Add Sound Sequence** - choose a sound file to use. You can use multiple sound files, and animate different things by
+  different sound files
+- **Remove Sound Sequence** - remove selected sound sequence
+- **Name** - name of the sequence. You can change it or copy the name to use it in the [driver](./drivers.md) expression
+- **Start Frame** - this is important! This is the frame when the sound sequence starts to play and also AudVis starts
+  to parse it
+- **Start Offset** - just offset - you can cut out the start of the song for example
+- **Length** - just length - you can cut out the end of the song for example
+- **Align End Frame by Sequences** - set current scene's End Frame to the last frame of all sound sequences - if your
+  song is 1234 frames long and starts at frame 1, end frame of the scene will be set to 1235