Fix grounding, preset save, update readme

.vscode/extensions.json

@@ -7,6 +7,7 @@
         "platformio.platformio-ide"
     ],
     "unwantedRecommendations": [
-        "ms-vscode.cpptools-extension-pack"
+        "ms-vscode.cpptools-extension-pack",
+        "pioarduino.pioarduino-ide"
     ]
 }

README.md

@@ -12,9 +12,9 @@ Samplotron is a standalone hardware sampler played with an external MIDI control
 
 ![Samplotron hardware sampler](Samplotron.jpg)
 
-The current photos show an earlier version played only through external MIDI. Photos of the version with the built-in keypad are coming soon.
+## Watch Samplotron in action
 
-[Why I built my own sampler — full article on Medium](https://medium.com/@KubaPisze/i-built-my-own-sampler-to-fit-my-needs-217493f4067c)
+[![Watch Samplotron in action — play the video on YouTube](docs/assets/youtube-preview.png)](https://www.youtube.com/watch?v=keyMwPUFDeM)
 
 For a walkthrough with screen photos, see the [musician's manual](docs/manual.md). Firmware binaries are available in the [latest main release](https://github.com/jakubthedeveloper/Samplotron/releases/tag/main-latest).
 
@@ -76,7 +76,7 @@ Pin assignments are defined in [include/pins.h](include/pins.h); keypad note map
 
 The audio output uses **one headphones-out channel (mono)** through a potentiometer wired as a voltage divider: one outer lug to the headphone signal, the other outer lug to ground, and the wiper to the output jack tip. Connect the jack sleeve to ground. At the headphone socket, use tip (L) or ring (R) relative to sleeve (ground), leaving the other channel unconnected. Both channels carry the same mono signal; 
 
-**Good grounding is essential:** use an electrically continuous metal enclosure, bring all device-side grounds to one star point, and bond it securely to the enclosure at a dedicated point. Do not rely on a jack or potentiometer mounting nut for the ground connection.
+**The output jack sleeve must be connected to both headphone output ground and the ESP32 GND pin.** Bring all device-side grounds to one star point, but keep them electrically isolated from the enclosure. Do not connect ground to the enclosure, including through jack or potentiometer mounting hardware: this can introduce OLED interference into the audio output.
 
 For normal operation, use the current build's dedicated power path: **9 V jack → step-down to 5 V → B0505S-3WR3 isolator → the AudioKit board's BAT connector**. The builder recommends good-quality guitar-pedal supplies over USB power. USB is still used for firmware programming. See [audio wiring, grounding and power](docs/documentation.md#audio-output-grounding-and-power) for the divider connections and isolated ground routing.
 
@@ -94,7 +94,24 @@ During boot, every loaded library entry (up to 32, including unassigned samples)
 
 No configuration file is required for first boot; without one, the device starts with no assignments, one-shot playback, and the default RAM budget.
 
-The repository includes a batch conversion command, requiring `ffmpeg` and Make:
+On Linux, install FFmpeg using your distribution's package manager (for example, `sudo apt install ffmpeg` on Debian/Ubuntu). Run this in Bash, setting `samples_dir` to the directory containing your WAV files:
+
+```bash
+samples_dir="/path/to/your samples"
+(
+    cd -- "$samples_dir" || exit 1
+    mkdir -p -- samplotron || exit 1
+    for file in *.[wW][aA][vV]; do
+        [ -f "$file" ] || continue
+        ffmpeg -nostdin -n -i "./$file" -map 0:a:0 -ac 1 -ar 44100 \
+            -c:a pcm_s16le -map_metadata -1 "samplotron/${file%.*}.wav" || exit 1
+    done
+)
+```
+
+This converts WAV files directly in the selected directory to uncompressed PCM16, 44.1 kHz, mono. Originals are preserved; output goes into its `samplotron` subdirectory, ready to copy to `/samples` on the SD card. Existing output files are not overwritten. This command does not trim silence or normalize volume.
+
+The repository also includes a batch conversion command, requiring `ffmpeg` and Make:
 
 ```bash
 make convert-samples SAMPLES_DIR=/path/to/sample-copies
@@ -131,6 +148,8 @@ With Make installed, the equivalents are `make build-main` and `make upload-main
 
 To flash without building, download `firmware.bin`, `bootloader.bin`, `partitions.bin`, and `boot_app0.bin` from the same [main-latest release](https://github.com/jakubthedeveloper/Samplotron/releases/tag/main-latest), then follow the [prebuilt firmware instructions](docs/documentation.md#flashing-prebuilt-firmware).
 
+Save failures appear on the OLED as compact codes such as `SAVE E15`. See [save error codes](docs/save-errors.md) for their meanings and diagnosis without a serial monitor.
+
 ### Tests
 
 Run the native tests without an ESP32 connected:

docs/documentation.md

@@ -62,12 +62,13 @@ The current hardware build takes **one channel of headphones out (mono)** throug
 | One headphone channel: tip (L) or ring (R) | One outer potentiometer lug |
 | Potentiometer wiper | Mono output jack tip |
 | Other outer potentiometer lug | Device ground star point |
-| Headphone ground / board GND | Device ground star point |
+| Headphone output ground (sleeve) | Device ground star point |
+| ESP32 GND pin | Device ground star point |
 | Mono output jack sleeve | Device ground star point |
 
 The potentiometer is a voltage divider, not a two-terminal series resistor. At maximum volume its wiper reaches the signal-side lug; at minimum it reaches the ground-side lug.
 
-**Grounding and enclosure continuity are essential.** Use a metal enclosure with electrical continuity across all its parts. Bring all device-side ground connections together in one star point, including board/headphone ground, the potentiometer ground lug, output jack sleeve and isolated power return. Bond that point to the enclosure through a dedicated, secure connection with good metal-to-metal contact. Do not use a jack or potentiometer mounting nut as the ground connection. Route a ground wire to the jack sleeve and the potentiometer ground lug rather than relying on mechanical mounting.
+**The output jack sleeve must be connected to both headphone output ground and the ESP32 GND pin.** Bring all device-side ground connections together in one star point, including headphone ground, ESP32 GND, the potentiometer ground lug, output jack sleeve and isolated power return. **Do not connect this ground to the enclosure: doing so can introduce OLED interference into the audio output.** Route ground wires to the jack sleeve and the potentiometer ground lug, and ensure that jack and potentiometer mounting hardware does not electrically connect ground to the enclosure.
 
 For normal operation, the builder recommends a dedicated supply jack instead of USB power. The tested power arrangement for this hardware revision is:
 

docs/manual.md

@@ -4,7 +4,7 @@ This guide focuses on making music with Samplotron: loading sounds, mapping them
 
 Connect the mono output jack to your mixer and start at a low monitoring volume. Inside Samplotron, **one headphones-out channel feeds a potentiometer used as a voltage divider**: one outer lug receives the headphone signal, the other connects to ground, and the wiper feeds the output jack tip. The jack sleeve connects to ground. Do not use the AudioKit's separate L/R speaker terminals: their Class-D amplifiers produce a switching, speaker-level signal unsuitable for this connection. Line-in and microphones are disabled; load samples from the SD card.
 
-For a quiet output, all device-side grounds meet at one star point, bonded to a metal enclosure with full electrical continuity through a dedicated, secure contact. A jack or potentiometer mounting nut must not serve as that ground connection.
+The output jack sleeve must be connected to both headphone output ground and the ESP32 GND pin. All device-side grounds meet at one star point and must remain electrically isolated from the enclosure, including at jack and potentiometer mounts. Connecting ground to the enclosure can introduce OLED interference into the audio output.
 
 The current build uses **9 V input → step-down to 5 V → B0505S-3WR3 isolator → the AudioKit board's BAT connector**, allowing good-quality guitar-pedal supplies. Prefer this dedicated power input over USB for normal operation; use the programming USB port for firmware updates. See the [build wiring](documentation.md#audio-output-grounding-and-power) for grounding and connector details.