Offline converter that turns PCM audio into RichTap HE haptic effect files
(HE 1.0 or HE 2.0). Each output file is a standalone HE effect, and a manifest.json
describes the chunking.
The algorithm and device calibration are ported from the current HD vibration implementation of GKME:
android/src/main/java/com/zyz4/gkme/haptic/PcmHeEncoder.kt— frame aggregation, edge-clustered 4-point curves, cross-chunk seam, start overshoot;android/src/main/java/com/zyz4/gkme/haptic/RichTapEngine.ktandRichTapFrequency.kt— HE↔Hz table, engine power law, amplitude-frequency compensation;android/src/main/java/com/zyz4/gkme/haptic/HdPcmStreamer.kt— event length, silence gate and start-overshoot constants.
See GKME's docs/richtap-hd-vibration.md (§9, §11, §13) for the real-device
measurements behind these rules.
The amplitude envelope and in-band dominant frequency of the PCM are mapped to
the HE Intensity / Frequency parameters:
- Read the audio, downmix to mono and resample to the analysis rate (48kHz by default).
- Band-pass 40–400Hz; use the 95th percentile of 40ms/5ms framed RMS as the reference level.
- Analyse frames every 10ms (
--hop-ms):- frame amplitude = frame RMS / reference;
- frequency = dominant in-band peak of a 40ms Hann-windowed FFT, then
shiftIntoRange(octave-up when too low, clamp when too high) and the real-device calibration table (hzToHe).
- Aggregate frames into events of
--event-ms(100ms by default):- event level =
max(mean, 0.85 × peak)— GKME's peak-hold (PEAK_MIX = 0.85), so attacks are not averaged down by the surrounding frames; - event frequency = mean HE of the frames;
- frames below the silence gate (
--silence, default4/255) are silence: they contribute a zero envelope and re-arm start detection.
- event level =
- Write each event as one
continuousevent whose curve has exactly 4 control points clustered at both ends (0, 2, D-2, D). The event starts at the previous event's end level, so the whole stream is one continuous piecewise-linear envelope — including across file/chunk boundaries. Empty or too-short event windows hold the previous level instead of jumping to zero. - Convert each control-point level to a curve intensity in the same way as GKME:
- compensate the LRA displacement response at the event's effective HE frequency
(
Q = 10, max boost2×); - invert the engine power law
a = c · 1.14^(10(c-1))withamplitudeToCurve.--linear-lawdisables both steps and writes the normalized envelope directly.
- compensate the LRA displacement response at the event's effective HE frequency
(
- Additionally insert a start-overshoot pulse on every silence → sound transition:
a short
continuousevent (default 5ms) at the start point. Its target ismin(1, startAmplitude × 5)and it is converted with the same law as the regular control points (default:amplitudeToCurve). This compensates the LRA spinning up from rest, so the first tens of milliseconds match the following level. Pulses may overlap regular events. - Split into multiple HE files by the number of regular events per effect (default 8); pulses occupy the remaining event slots.
- Trim trailing silence across chunks.
Real-device hard constraints (see the GKME docs): at most 16 events per effect, exactly 4 curve points per event, and at most 5000ms per event.
Requires g++ (C++17). On Windows:
.\build.ps1 # produces build\pcm2he.exe
.\build.ps1 -Clean # clean rebuildOr with CMake:
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Releasepcm2he [options] <input-audio>
# WAV -> HE 1.0
.\build\pcm2he.exe -o out sample.wav
# WAV -> HE 2.0, 4 events per effect
.\build\pcm2he.exe --version 2 --events-per-chunk 4 -o out sample.wav
# Raw PCM (float32 mono 48k)
.\build\pcm2he.exe --raw --format f32 --rate 48000 --channels 1 -o out src.f32
# Legacy direct envelope (disable GKME's inverse engine law + compensation)
.\build\pcm2he.exe --linear-law -o out sample.wavMain options:
| Option | Description | Default |
|---|---|---|
-o, --outdir DIR |
Output directory | ./out |
--version 1|2 |
Output HE version | 1 |
--event-ms MS |
Duration of each event (time resolution) | 100 |
--events-per-chunk N |
Regular events per effect/file (1..16) | 8 |
--analysis-rate HZ |
Analysis/resample target rate | 48000 |
--low HZ / --high HZ |
Analysis band-pass range | 40 / 400 |
--gamma X |
Envelope compression exponent | 1.0 |
--linear-law |
Skip frequency compensation + inverse engine law | off |
--silence X |
Treat frames below X × reference as silence |
4/255 |
--accent-ms MS |
Start-overshoot pulse duration | 5 (0=off) |
--start-overshoot X |
Start-overshoot gain | 5.0 |
--peak-mix X |
Event peak-hold mix: max(mean, peak × X) |
0.85 |
--hop-ms MS |
Frame interval for envelope/frequency | 10 |
--raw / --format / --rate / --channels |
Raw PCM input parameters | f32 / 48000 / 1 |
A single HE effect holds at most 16 events (a real-device hard constraint). Regular
events occupy --events-per-chunk slots and the rest are left for start-overshoot pulses.
Therefore:
- If pulse-heavy material reports
droppedpulses, lower--events-per-chunk(e.g.2~4) to free up space; - To disable start pulses use
--accent-ms 0, and--events-per-chunkcan go back to16; - GKME's realtime streamer uses
100ms × 2events (200ms/effect) to keep the first-frame latency low. Offline conversion has no latency budget, and larger chunks have fewer boundaries (measured smoother: 200ms ≈ 6.4% amplitude variation, 800ms ≈ 3.2%), so the default here is100ms × 8(800ms). Increase it up to16for even smoother output.
- The old onset accent and short-transient (burst) detectors are gone. They are
replaced by GKME's single start-overshoot rule (silence → sound), so
--burst-msis no longer accepted. - Defaults now match the current GKME logic:
--event-ms 100,--gamma 1.0, inverse engine law on, silence gate4/255, peak-hold mix0.85. - Envelope/frequency features are analysed per 10ms frame and aggregated per event, instead of one RMS/F0 value per event.
--pulse-hop-mswas renamed to--hop-ms(the old name still works).--inverse-lawis still accepted for compatibility but is now the default; use--linear-lawfor the legacy direct-envelope output.
out/
chunk_000.json # one HE effect
chunk_001.json
...
manifest.json # chunk metadata
--version 1: top level isPattern;--version 2: top level isPatternList, one item per event, withAbsoluteTimeas the event start time;manifest.json:event_ms,events_per_chunk,chunk_ms,frame_hop_ms,he_version,sample_rate,chunks.
src/
main.cpp CLI entry point
audio.h/.cpp WAV / raw PCM reading, downmix, resample
dsp.h/.cpp biquad band-pass, FFT, envelope/dominant-frequency features
richtap.h/.cpp HE<->Hz calibration table, amplitude law, frequency compensation
encoder.h/.cpp frame aggregation, HE 1.0/2.0 assembly, pulses, chunked output
- The frame amplitude is the RMS of the band-passed mono signal relative to a 95th percentile reference, while GKME's realtime path uses the voice-coil frame amplitude (0–255). The normalized envelope is therefore similar but not bit-identical.
- GKME's pitch tracker (
service/PcmPitchTracker.kt) uses a Hilbert analytic signal, pitch smoothing and tonality gating; this offline tool keeps a simpler 40ms Hann-FFT dominant-frequency estimator so it stays dependency-free. - Pulse insertion is subject to the 16-event cap; overflow is dropped and reported at runtime.
- The band-pass uses cascaded RBJ biquads instead of a scipy Butterworth filter, so the envelope shape differs slightly; after reference-level normalization the impact is limited.
- The mechanical Q for frequency compensation is fixed at
10and not device-calibrated.
Released under the MIT License. Algorithm and frequency calibration data ported from GKME (Copyright (c) 4zyz4).