Skip to content
4zyz4Public

About

Convert PCM audio into RichTap HE haptic effect files (HE 1.0 / 2.0)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

PCM2He

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.kt and RichTapFrequency.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.

How it works

The amplitude envelope and in-band dominant frequency of the PCM are mapped to the HE Intensity / Frequency parameters:

  1. Read the audio, downmix to mono and resample to the analysis rate (48kHz by default).
  2. Band-pass 40–400Hz; use the 95th percentile of 40ms/5ms framed RMS as the reference level.
  3. 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).
  4. 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, default 4/255) are silence: they contribute a zero envelope and re-arm start detection.
  5. Write each event as one continuous event 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.
  6. 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 boost 2×);
    • invert the engine power law a = c · 1.14^(10(c-1)) with amplitudeToCurve. --linear-law disables both steps and writes the normalized envelope directly.
  7. Additionally insert a start-overshoot pulse on every silence → sound transition: a short continuous event (default 5ms) at the start point. Its target is min(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.
  8. Split into multiple HE files by the number of regular events per effect (default 8); pulses occupy the remaining event slots.
  9. 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.

Build

Requires g++ (C++17). On Windows:

.\build.ps1            # produces build\pcm2he.exe
.\build.ps1 -Clean     # clean rebuild

Or with CMake:

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

Usage

pcm2he [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.wav

Main 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

Chunking, pulses and event slots

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 dropped pulses, lower --events-per-chunk (e.g. 2~4) to free up space;
  • To disable start pulses use --accent-ms 0, and --events-per-chunk can go back to 16;
  • GKME's realtime streamer uses 100ms × 2 events (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 is 100ms × 8 (800ms). Increase it up to 16 for even smoother output.

Changes from the previous version

  • 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-ms is no longer accepted.
  • Defaults now match the current GKME logic: --event-ms 100, --gamma 1.0, inverse engine law on, silence gate 4/255, peak-hold mix 0.85.
  • Envelope/frequency features are analysed per 10ms frame and aggregated per event, instead of one RMS/F0 value per event.
  • --pulse-hop-ms was renamed to --hop-ms (the old name still works). --inverse-law is still accepted for compatibility but is now the default; use --linear-law for the legacy direct-envelope output.

Output

out/
  chunk_000.json   # one HE effect
  chunk_001.json
  ...
  manifest.json    # chunk metadata
  • --version 1: top level is Pattern;
  • --version 2: top level is PatternList, one item per event, with AbsoluteTime as the event start time;
  • manifest.json: event_ms, events_per_chunk, chunk_ms, frame_hop_ms, he_version, sample_rate, chunks.

Project layout

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

Known limitations

  • 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 10 and not device-calibrated.

License

Released under the MIT License. Algorithm and frequency calibration data ported from GKME (Copyright (c) 4zyz4).

About

Convert PCM audio into RichTap HE haptic effect files (HE 1.0 / 2.0)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages