documentation draft

docs/SharkPool/Tune-Shark-V3.md

@@ -0,0 +1,255 @@
+# Tune Shark V3
+Tune Shark V3 is a powerful audio engine that is built to give you full control over your sounds. It allows you to apply numerous audio effects, precisely measure sound outputs, and more!
+This is a remaster of the now deprecated Tune Shark extension by SharkPool.
+
+## General Setup
+
+### Note: All Tune Shark sounds are globally accessible in your project. This means all sprites will be able to access a loaded sound.
+
+```scratch
+⚙️ import sound from URL [https://...] named [MySound] ::#666666
+```
+
+You can import "Tune Shark" sounds via URL/URI using this block. It is important to note that URLs *must* be a **direct** link to an audio file
+
+```scratch
+⚙️ import sound (Meow v) named [MySound] ::#666666
+```
+
+Alternatively, you can import "Tune Shark" sounds from pre-existing sounds from the "Sounds" tab in the editor.
+
+```scratch
+⚙️ convert sound [MySound] from URL to URI and save to [MySound2] ::#666666
+```
+
+This block will convert the inputted sound's source from a URL to a data:URI. It will save this new sound as a new "Tune Shark" sound.
+
+```scratch
+⚙️ [bind v] sound [MySound] and sound [MySound2] ::#666666
+```
+
+This block allows you to bind or unbind the first inputted sound to the second. This means when you play "MySound2", "MySound" will play as well.
+This **does not** go the same way in reverse.
+
+```scratch
+⚙️ [save v] all sounds to project ::#666666
+```
+
+This block saves all currently loaded Tune Shark sounds into the project so that they may be automatically loaded when the project opens.
+You can stop this by using the "dont save" option in the block menu.
+
+## Audio Playback
+
+```scratch
+🎵 start sound [MySound] ::#666666
+```
+Similar to Scratch, this will start a sound from the beginning.
+
+```scratch
+🎵 start sound [MySound] at time (5) ::#666666
+```
+
+You can also start sounds at certain points in the track using this block. This is measured in seconds.
+
+```scratch
+🎵 start sound [MySound] at time (0) and stop at (2) ::#666666
+```
+
+Similar to the above block, this block will start a sound at a certain point, then **waits** until the sound reaches the stopping point.
+
+```scratch
+🎵 stop sound [MySound] ::#666666
+```
+
+This block will stop the inputted sound.
+
+```scratch
+🎵 [pause v] sound [MySound] ::#666666
+```
+
+This block will pause/unpause the inputted sound.
+
+```scratch
+🎵 [start v] all sounds ::#666666
+```
+
+This block controls all loaded sounds. You can:
+- start all sounds
+- stop all sounds
+- pause all sounds
+- unpause all sounds
+
+## Operations
+
+```scratch
+⚙️ toggle sound link to @greenFlag @stopSign [on v] ::#666666
+```
+
+Toggling this operator on will cause Tune Shark sounds to stop when the green flag or stop sign is clicked.
+
+```scratch
+⚙️ toggle sound [MySound] overlapping [on v] ::#666666
+```
+
+Toggling this operator on will allow multiple instances of a sound to play at once.
+Normally, you can only play one instance of a sound at a time.
+
+```scratch
+⚙️ toggle sound [MySound] reverse mode [on v] ::#666666
+```
+
+Toggling this operator on will make the inputted ound play in reverse. Toggling it off will return it back to normal.
+
+```scratch
+⚙️ toggle sound [MySound] looping [on v] ::#666666
+```
+
+Toggling this operator on will allow the inputted sound to loop.
+
+```scratch
+⚙️ sound [MySound] loop start (0) end (2) ::#666666
+```
+
+You can mess around with the loop starting point and ending point with this block.
+
+```scratch
+⚙️ delete sound [MySound] ::#666666
+```
+
+This block will delete the inputted sound.
+
+```scratch
+⚙️ delete all sounds ::#666666
+```
+
+This block will delete all loaded sounds.
+
+```scratch
+(⚙️ all sounds ::#666666)
+```
+
+This block will return an array of the names of all loaded Tune Shark sounds.
+
+```scratch
+(⚙️ all playing sounds ::#666666)
+```
+
+Similarly, this block returns an array of the names of all loaded Tune Shark sounds that are currently playing.
+
+```scratch
+⚙️ when sound [MySound] [starts v] ::#666666 hat
+```
+
+This event block runs whenever the inputted sound starts or ends.
+
+```scratch
+<⚙️ sound [MySound] (exists v)? ::#666666>
+```
+
+Returns various information of a sound:
+Options | What they Check for
+--- | ---
+exists | if the sound exists
+playing | if the sound is playing
+paused | if the sound is paused
+looped | if the sound is looping
+overlaped | if the sound allows instancing
+reversed | if the sound is reversed
+binded | if the sound is binded to another
+
+```scratch
+(⚙️ (length v) of sound [MySound] ::#666666)
+```
+
+Returns various information of a sound:
+Options | What they Do
+--- | ---
+length | sound length (in seconds)
+current time | current position in a sound
+source | source URL/URI of a sound
+estimated bpm | estimated beats-per-minute
+channels | the number of [channels](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Audio_concepts) in a sound
+binds | an array of sound names binded to this sound
+*...various audio effects* | returns the inputted parameters for the effect
+
+```scratch
+(⚙️ [loudness v] of sound [MySound] at time (0) in channel (1) ::#666666)
+```
+
+You can read sound outputs using this block.
+
+If you select **"loudness"**, it returns a normalized volume of the outputted noise at a specific point in the sound.
+
+Similarly, **"raw noise"** returns the outputted volume, but its *not normalized*
+
+Selecting **"tone"** will return the outputted pitch of a sound at a specific point.
+
+
+The channel input selects which [sound channel](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Audio_concepts) to extract the output data from.
+Typically, if there are 2 channels, channel 1 is "Left Ear" and channel 2 is "Right Ear".
+
+## Audio Effects
+
+```scratch
+🎛️ set volume of sound [MySound] to (100) ::#666666
+```
+
+This block simply sets the volume of the inputted sound.
+
+```scratch
+🎛️ reset (all effects v) of sound [MySound] ::#666666
+```
+
+This block resets the values of each audio effect in a sound to the default (not including volume).
+
+```scratch
+🎛️ set (pitch v) of sound [MySound] to (0) ::#666666
+```
+
+Sets the effect of a selected sound to a inputted value.
+Effect List | What they Do
+--- | ---
+pitch | changes the speed and tone of the sound
+detune | changes the speed and semitone of the sound
+speed | changes the speed of the sound without affecting pitch
+pan | shifts sound to the left (negative) or right (positive) ear
+gain | boosts the sounds volume beyond 100
+distortion | distorts/crushes sound
+attack | fade-in time when sound starts
+release | fade-out time when sound stops
+
+```scratch
+🎛️ set reverb of sound [MySound] to time (100) decay (100) mix (50) ::#666666
+```
+
+```scratch
+🎛️ set delay of sound [MySound] to time (50) feedback (60) mix (50) ::#666666
+```
+
+```scratch
+🎛️ set tremolo of sound [MySound] to speed (35) depth (80) mix (100) ::#666666
+```
+
+```scratch
+🎛️ set fuzz of sound [MySound] to low (60) med-low (50) med-high (80) high (60) mix (50) ::#666666
+```
+
+```scratch
+🎛️ set bitcrush of sound [MySound] to bits (65) freq (60000) ::#666666
+```
+
+```scratch
+🎛️ set [highpass v] of sound [MySound] to frequency (400) peak (10) ::#666666
+```
+
+```scratch
+🎛️ set flanger of sound [MySound] to time (45) speed (20) depth (10) feed (10) mix (50) ::#666666
+```
+
+```scratch
+🎛️ set compressor of sound [MySound] to threshold (15) knee (50) attack (50) release (50) ratio (50) ::#666666
+```
+
+```scratch
+🎛️ set equalizer of sound [MySound] to gain low (100) med (100) high (100) cutoff low (-50) cutoff high (50) ::#666666
+```