README

libsox.sh
---------

A library for GNU bash making it easier to create music with the power of SoX
synths.

If you're one of these people:

- a Bash programmer
- suck at reading sheet music
- finds MML too difficult
- too lazy to learn FamiTracker
- think that scientific note duration is the best thing since sliced bread

Then try this crappy library of mine!

Some features of this library:

- Easy to write syntax for inputting notes ("$duration:${key[pitch]}")
 - Inspired from korobeiniki.sh of the dsuni/bashtris repository
- Supports two-note harmonies ("$duration:${key1[pitch1]},${key2[pitch2]}")
 - Must be the same duration and instrument
- Optionally supports 3/4/5/6-note harmonies as well
 -"$duration:${k1[p1]},${k2[p2]}*${k3[p3]}_${k4[p4]@${k5[p5]}}^${k6[p6]}"
 -You need to call "enable3456Harmony" to enable this feature
 -For ALSA, you also need to set sox's audio processing buffer to 16384 bytes,
  else you will get underrun
- Supports every synth type included in SoX
- Adheres to the Unix philosophy of "do one thing and do it well"

What this library doesn't support:

- Using your own samples (just use FamiTracker or a DAW for that)
- Harmonies with different durations or instruments
- POSIX compatibility

Usage
-----

Simply source libsox.sh into the script containing the music. Example scripts
are included in this repository.

Example child script syntax
---------------------------

./music.sh | xargs play -S -V1 # Plays into SoX once

./music.sh | xargs ./myplay-repeat.sh 1 # Plays into SoX twice

./music.sh | xargs ./mysox.sh music.wav # Saves into "music.wav" using SoX

./music.sh | head -n +37 | xargs play -S -V1 ; ./music.sh | tail -n +37 |
 xargs ./myplay-repeat.sh 3    # Plays line 1 to 37 of music.sh's output once,
                                 then plays the rest thrice

./music.sh | xargs ./mysox.sh - | cvlc - # Saves into stdout then pipes it into
                                           vlc
./music.sh > music.txt         # Redirects music.sh's output to a text file

./music.sh | xclip -i          # Copies music.sh's output to XA_PRIMARY

Usual child script format
-------------------------
##############################################################################
#!/bin/bash

: '
Long copyright boilerplate goes here.
It's up to you though if you want to include it or not.
'

source path/to/libsox.sh

declare textintro='
Optional ASCII art and info about the music goes here.

'

setTempo 120 # In BPM

setDefaultSynthType sin # Consult sox's manual. Default is sine

notes=(
 # "$duration:${note[pitch]}"

 # Basic durations:
 #  $fu = whole note
 #  $ha = half note
 #  $qu = quarter note
 #  $ei = eighth note
 #  $si = sixteenth note
 # We use scientific pitch notation

 "$ha:0" # This is how to do a half rest

 "$si:${c[5]}" # A sixteenth C note in the 5th octave
 "$ei:${gs[4]}" # An eighth G sharp in 4th octave
 "$qu:${gf[4]}" # A quarter G flat in 4th octave
 "$qu:${gb[4]}" # Also a G flat
)

function repeatingNotes { # Use bash functions to repeat parts of your music
 notes+=( # use += to append to the notes array
  "$qu:${cs[4]}"
  "$qu:${ds[4]}"
  "$qu:${e[3]}"
  "$qu:${gs[4]}"
 )
}
repeatingNotes # Don't forget to call your function
notes+=( # continue adding notes
 "$ei:${cs[4]}"
 "$ei:${cs[4]}"
 "$ei:${ds[4]}"
 "$ei:${ds[4]}"
)
repeatingNotes # Will repeat the earlier C sharp, D sharp, E, and G sharp
               # quarter notes
notes+=(
 "$dei:${b[2]}" # Dotted notes are supported
 "$tqu:${a[3]}" # Triplets are supported
 "0.02:${gs[4]}" # You can do custom durations
 "0.05:489 # Custom frequencies too
)

createSoxPipes # Will reset the notes array too
echo # Useful for distinguishing the part that loops and the part that doesn't

# Loop start
setTempo 160 # Change the BPM if needed

setDefaultSynthType pluck # You can change the synth type midway.

notes+=(
 "$dei:${fs[5]},${gs[5]}" # You can do two-note harmonies
 "$dei:${c[6]}"
 "$ei:${as[5]}"
 "$ha:${as[5]}"
 "$ei:${as[5]}"
)
function commonNotes {
 notes+=(
  "$si:${cs[5]}"
  "$si:${gs[4]}"
  "$si:${fs[4]}"
 )
 silence # Required if you're using a synth type that doesn't support freq=0
 notes+=(
  "$si:${e[4]}"
  "$si:${cs[5]}"
 )
}
commonNotes; commonNotes;
notes+=(
 "$qu:${c[4]}"
 "$qu:${cs[4]}"
 "$qu:${ds[4]}"
 "$ei:${f[4]}"
 "$si:${as[4]}"
 "$dei:${f[4]}"
)
commonNotes
notes+=(
 "$dei:${f[4]}"
 "$ei:${as[4]}"
 "$ei:${a[4]}"
 "$ei:${a[4]}"
 "$ei:${as[4]}"
 "$si:${a[4]}"
 "$si:${as[4]}"
 "$si:${f[5]}"
)

createSoxPipes

##############################################################################

License
-------

Copyright (C) 2022 Job Bautista

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.