Sound Lab - installing on a Miyoo Mini Plus with Onion OS
=========================================================

Version: v1.0.2
Author: slop.kitchen
Website: https://slop.kitchen/soundlab

Sound Lab is a music player, synthesizer, sequencer and drum machine for the Miyoo Mini Plus
with Onion OS 4.4 (tested on 4.4.0). Play its 38 built-in pieces and the included recordings,
add your own MP3 and WAV files, open any piece in an eight-track sequencer, shape its sounds,
play twelve drum pads and watch it all on a live spectrum analyzer. It appears in Onion's
Apps list: Apps > Sound Lab. This zip holds only the app and bundled music; it never
contains your projects or recordings. Updates keep your files.

What the zip puts on the SD card
--------------------------------

  App/SoundLab/soundlab             the app
  App/SoundLab/soundlab-audio       native audio helper
  App/SoundLab/launch.sh            starts it and restores Onion's audio on exit
  App/SoundLab/music/               the included recordings: Euphoric Defiance,
                                    its six loop arrangements and LOOPS.json
  App/SoundLab/cacert.pem           certificates for the phone microphone's setup
  App/SoundLab/INSTALL.txt          this file
  App/SoundLab/CHANGELOG.md         what changed in each version
  App/SoundLab/LICENSE.txt          Sound Lab's license
  App/SoundLab/MUSIC_CREDITS.txt    credits for every piece and recording
  App/SoundLab/OFL.txt              the Exo 2 font's license (SIL Open Font License 1.1)
  App/SoundLab/AUDIO-CODECS.txt     the MP3 decoder's license notices
  App/SoundLab/HTTPS-LICENSES.txt   the network libraries' license notices
  App/SoundLab/config.json          the entry in the Apps list
  App/SoundLab/icon.png             its icon
  App/SoundLab/migrate.sh           safely moves files from the older Ports install

Sound Lab uses the handheld's own audio libraries, which stay on the handheld and are not in
this zip. Start with the volume low, especially on headphones.


Install
-------

If you use Mixtape, the app store for Onion OS on the handheld, it can install and update
Sound Lab over Wi-Fi instead: see https://slop.kitchen/soundlab. Otherwise:

1. Turn the handheld off and put its SD card in your computer.
2. Extract the zip to the ROOT of the SD card (the top level, where the Roms, App and Emu
   folders are), so that its App folder merges with the card's App folder. Nothing on the
   card is deleted; only the files listed above are added.
   - Windows: open the zip, select the App folder inside it, and copy it onto the card's top
     level (Explorer merges folders). Answer "Replace" if it asks about Sound Lab's files.
   - macOS: do NOT drag the App folder onto the card in Finder: Finder's default is to
     REPLACE the card's whole App folder, which deletes your apps. Use Terminal instead
     (change SDCARD to your card's name as Finder shows it, keeping the quotes):
         unzip -o ~/Downloads/SoundLab-v1.0.2.zip -d "/Volumes/SDCARD"
         dot_clean -m "/Volumes/SDCARD"
     (dot_clean -m removes the "._" files macOS leaves on memory cards.)
     Safari unzips downloads and deletes the zip. If it did, copy the App folder it left in
     Downloads instead, then remove it (so the next update's folder gets the same name):
         rsync -r ~/Downloads/App/ "/Volumes/SDCARD/App/" && rm -r ~/Downloads/App
         dot_clean -m "/Volumes/SDCARD"
   - Linux: unzip -o SoundLab-v1.0.2.zip -d /path/to/the/card
3. Check that the card now has App/SoundLab/soundlab (not a
   SoundLab-v1.0.2 folder at the top with App inside it).
4. Eject the card safely, put it back in the handheld and turn it on.
5. Open Apps > Sound Lab. No Ports Collection or import step is needed.


Moving from Ports (1.0.0 and earlier builds)
-------------------------------------------

Quit the old Sound Lab with MENU before updating. Install the new zip as above, or update
in Mixtape, then open Apps > Sound Lab. On the first launch Sound Lab copies your projects,
patches, exports, saved session, drum kits, settings, microphone setup and own recordings
from Roms/PORTS/Games/SoundLab/ to App/SoundLab/. Each copy is checked before the old Ports
shortcut is hidden. The old folder remains as a backup. Direct commands to its old
launch.sh forward to Apps. Reopen Sound Lab through Apps after the move: an older Ports
entry in Recents may no longer open.

If both folders already contain DIFFERENT versions of a user file, migration stops before
starting the app and leaves both versions intact. Read App/SoundLab/migration.log for the
filename. On your computer, back up BOTH SoundLab folders. Choose the copy you want to use:
move the other copy out of its SoundLab folder, or make the two copies identical, then open
Apps > Sound Lab again. Do not delete the old folder until your projects and recordings
appear correctly in Apps. A failed or interrupted copy can be retried the same way.

After checking the new app, you may remove Roms/PORTS/Games/SoundLab/ and the archived
Roms/PORTS/Shortcuts/Tools/Sound Lab.port.migrated (or .notfound.migrated), plus its old
Roms/PORTS/Imgs/Sound Lab.png. Keep a backup of your files before deleting anything.
Stable and DEV are separate installs; each migrates only its own older Ports folder.


Getting started
---------------

Sound Lab opens on MUSIC. Up/Down browses the 38 built-in pieces and A plays one; keep
browsing while it plays. START plays or stops the current piece. The Now Playing panel shows
what you hear, how far along it is and its levels.

Press Y on MUSIC for RECORDINGS: Euphoric Defiance and six loop arrangements of it (Menu,
Menu Alt, Flow A, Flow B, Pressure and Defiance). A plays the selected file or pauses it,
START pauses and resumes, B stops and rewinds, Left/Right seeks five seconds, X repeats the
file and L2/R2 sets the recording's volume. Each loop arrangement is 64 bars at 147 BPM and
repeats without a gap when X is on. A recording keeps playing while you use the other tabs;
starting a built-in piece stops it. Y returns to the built-in pieces.

Every built-in piece can be edited: press X on MUSIC to open the current arrangement in
SEQUENCER. L1/R1 moves between the tabs: MUSIC, SEQUENCER, MIXER, SOUND, LIBRARY, FILES and
ANALYZER.

  SEQUENCER   eight tracks of one to sixteen bars. A sets a step; hold B and press L1/R1 to
              change its note, or Up/Down for its velocity; hold A and press L1/R1 for the
              length; hold Y and press L1/R1 for the tempo; tap Y to follow playback.
  MIXER       each track's level, pan and root note; Left/Right picks level, pan, note or
              master, and holding Y and pressing L1/R1 changes it. A adds a minor chord,
              X mutes.
  SOUND       the selected track's sound: wave (including a sampled grand piano), envelope,
              pitch sweep, filter, detune, noise and a fast chip arpeggio. Hold Y and press
              L1/R1 to change the selected value; hold A as well for bigger steps.
  LIBRARY     sixteen game-sound recipes, each with eight variations: Left/Right picks a
              variation, B previews it, A applies it to the selected track. The DRUM
              MACHINE card is at the top.
  FILES       eight project slots and eight patch slots to save and load, and exports.
  ANALYZER    a live spectrogram, scope and level meters, and reference tones (hold B).

DRUM MACHINE (LIBRARY, press Up from the first recipe, then A): Up/Down chooses a pad and
Left/Right gives it one of 32 sounds. START switches to PERFORM, where the D-pad, A/B/X/Y and
all four shoulder buttons are twelve pads. SELECT changes kit (classic, electro, chip, FX);
each kit remembers its pads. START goes back to choosing sounds, and B returns to LIBRARY.

Replacing a piece you have edited asks first: A replaces it, B keeps it. Save variations you
want to keep in FILES. Sound Lab also keeps your current session and restores it the next
time you start it.


Controls
--------

  D-pad       browse pieces and files; choose a track, step, value or file action
  A           play the selection; set a step; choose or confirm
  B           hear the selected sound; cancel; hold for note and velocity edits
  X           open the current arrangement in SEQUENCER; mute a track
  Y           switch between built-in pieces and recordings; hold for shortcuts
  L1 / R1     previous / next tab
  L2 / R2     previous / next track; recording volume
  START       play / stop; pause / resume a recording; drum machine mode
  SELECT      the control guide for the page you are on (on DRUM MACHINE: next kit)
  MENU        quit (your session is kept)

Hold the modifier (B, Y or A) before pressing the second button. SELECT shows every control
of the page you are on.

ANALYZER also has: Up/Down picks a reference tone and Left/Right sends it left, centre or
right; A freezes the display and X clears it; hold Y and press L1 to change the speaker EQ
(OFF, LIGHT, MEDIUM or STRONG; it brings out bass on the handheld's small speaker; use OFF for
headphones), R1 to turn the spectrum off, or X for the phone microphone.


About and website
-----------------

In the control guide (SELECT), press X for ABOUT: Sound Lab's version and a QR code. Scan it
with a phone camera to open https://slop.kitchen/soundlab for updates and help. B returns
to the guide; SELECT returns to your page. START still plays and stops music.


Your own music
--------------

Copy MP3 files, or uncompressed 16-bit PCM WAV files (mono or stereo, 8 to 48 kHz), to:

    App/SoundLab/music/

Then return to RECORDINGS to see them. It lists up to 64 files in that folder (not in
folders inside it). AAC/M4A and compressed WAV files do not play. A file you add is not a
seamless loop unless it was made as one.


Your files
----------

Sound Lab keeps everything you make next to it, in App/SoundLab/:

  project-1.txt ... project-8.txt   your saved projects
  patch-1.txt ... patch-8.txt       your saved sounds
  project-N-loop.wav, .h, .txt      exported loops (WAV, a C file and a description)
  patch-N-sound.wav, .h, .txt       exported sounds
  autosave.txt                      the session Sound Lab restores when you start it
  drums.txt                         your drum kits
  settings.txt                      the speaker EQ
  music/                            the included recordings and your own
  phone-mic.conf, phone-mic/        the phone microphone's setup, if you use it
  log.txt, audio-helper.log         what Sound Lab did the last time it ran
  ports-migration.txt, migration.log  the completed move from Ports and any migration errors

Each save keeps the previous version as a .bak file next to it. Updates never replace or
delete any of these, except the included recordings in music/, which are updated by name.
To keep your files safe, copy them off the card now and then.


Phone microphone (experimental)
-------------------------------

Sound Lab can show your phone's microphone on its analyzer, over Wi-Fi. Use it only on your
own home Wi-Fi network, not on public or shared Wi-Fi.

1. Connect the handheld and the phone to the same Wi-Fi, and set the handheld's date and time.
2. On ANALYZER, hold Y and press X, release both, then press A to start the receiver. Music
   stops.
3. Scan the QR code with the phone, tap Start microphone and allow the microphone. Speak or
   clap: the handheld switches to the live spectrum.
4. Keep the page open on the phone. Stop microphone on the phone, or A on the handheld,
   stops it. X switches between the QR code and the spectrum; B returns to ANALYZER, which
   shows the phone's sound while it keeps listening.

The receiver runs only on the Phone Microphone screen and ANALYZER (and the guide opened from
them). Going to any other tab stops it, and so does starting a recording. While it runs, the
top of the screen shows a red dot and MIC ON.

The sound goes straight from the phone to the handheld over your network. It is not
recorded, saved or played aloud. One phone at a time; scan the new QR code each time you
start the receiver.

The first start needs the Internet to fetch a certificate from local-ip.sh, which Sound Lab
keeps in phone-mic/ and renews before it expires; the phone needs working DNS to open the
link. If it fails, check the Wi-Fi, the date and time, the Internet connection and free space
on the card, then press A to try again. Guest networks that keep devices apart, or routers
that block local addresses in DNS, stop the phone from connecting. If the phone shows a
certificate warning, do not bypass it. If you denied the microphone, allow it in the
browser's settings for the site.

local-ip.sh publishes the private key of its certificate, so on a network you do not trust
someone could pretend to be your handheld. For your own certificate, put a phone-mic.conf
next to Sound Lab, with a DNS name that points to the handheld:

    hostname=miyoo.example.com
    port=8443
    certificate=phone-mic/fullchain.pem
    private_key=phone-mic/privkey.pem

The certificate chain must be current and trusted by your phone, and the private key
unencrypted PEM. Paths are relative to Sound Lab's folder, or absolute. Stop and start the
receiver after a change; remove phone-mic.conf to go back to the automatic setup.


Update to a new version
-----------------------

Quit Sound Lab first (MENU). Then install the new zip exactly as above, replacing the old
files when asked, or update it in Mixtape. Your files are not in the zip, so they stay as
they are. The included recordings in music/ are updated by name; your own recordings there
are kept.


Uninstall
---------

Quit Sound Lab, then delete App/SoundLab/ from the SD card. This also deletes your
projects, sounds, exports and recordings: copy them first if you want to keep them.
If you upgraded from Ports, its backup folder and archived shortcut can be removed as
described in Moving from Ports above.



If there is no sound
--------------------

Press START, or hold B on ANALYZER for a reference tone, and watch the meters. The bottom line
of FILES and ANALYZER says whether the sound output is working, with an error code if not. If
the meters move but you hear nothing, turn the volume up with the handheld's volume buttons.


Problems
--------

Sound Lab writes what it does to App/SoundLab/log.txt, and its audio start-up to
audio-helper.log. Include both files when you report a problem, with the version shown in the top bar
or ABOUT (v1.0.2): https://slop.kitchen/soundlab.
