Wow and Flutter Phyphox Preprocessor
===================================

Overview
--------
This project includes a standalone preprocessor script:

    phyphox_preprocessor.py

The script reads a .phyphox gyroscope recording, selects a stable measurement
segment, synthesizes a 2-channel WAV file (24-bit, 96 kHz), and then runs the
existing analysis pipeline (wf_analyze.py + wf_core.py) on that WAV.

It also writes a text metrics report.


What this script is for
-----------------------
Use this script when your turntable speed measurement source is phyphox.
The generated WAV is intentionally created so it can be analyzed by the original
scripts without modifying them.


Files involved
--------------
Input:
- <name>.phyphox

Main script:
- phyphox_preprocessor.py

Original analysis scripts (used by preprocessor):
- wf_analyze.py
- wf_core.py

Outputs:
- <prefix>.wav
- <prefix>_analysis.png
- <prefix>_metrics.txt

Default prefix:
- <input_filename_without_extension>_preprocessed


Requirements
------------
- Python 3.8+
- numpy
- scipy
- matplotlib
- soundfile

Install example:

    pip install numpy scipy matplotlib soundfile


Quick start
-----------
Run with defaults (RPM default is 33.3333333333):

    python phyphox_preprocessor.py input.phyphox

  Recommended speed option:

    python phyphox_preprocessor.py input.phyphox --rsp 1

Run for 45 RPM context:

  python phyphox_preprocessor.py input.phyphox --rsp 2

Select gyroscope axis explicitly:

    python phyphox_preprocessor.py input.phyphox --axis z


Command-line options
--------------------
Required:
- input
  Path to input .phyphox file.

Common options:
- --rpm <float>
- --rsp <1|2|3>
  Rotational SPeed selector (recommended):
    - --rsp 1 -> 100/3 RPM (33.333333333333...)
    - --rsp 2 -> 45.0 RPM
    - --rsp 3 -> 78.0 RPM
  If omitted, default is --rsp 1.

- --rpm <float>
  Fallback input form. Accepted families only:
    - any 33.* value -> 33.3333333333
    - any 45.* value -> 45.0
    - any 78.* value -> 78.0
  Do not combine with --rsp.

- --axis <auto|x|y|z|abs>
  Gyroscope channel selection from phyphox.
  Default: auto

- --trim-start-s <float>
  Seconds removed from start before stable-segment selection.
  Default: 8.0

- --trim-end-s <float>
  Seconds removed from end before stable-segment selection.
  Default: 8.0

- --stable-window-s <float>
  Rolling window length for local stability estimation.
  Default: 2.0

- --stable-factor <float>
  Threshold multiplier over median local standard deviation.
  Default: 1.35

- --min-stable-s <float>
  Minimum accepted stable segment length.
  Default: 20.0

- --carrier-hz <float>
  Carrier used in synthesized WAV.
  Default: 1000.0

- --wav-sr <int>
  WAV sample rate.
  Default: 96000

- --out-prefix <string>
  Custom output file prefix.

Pass-through options for harmonic labeling:
- --motor-slots <int>
- --motor-poles <int>
- --drive-ratio <float>


How the processing works
------------------------
1) Parse phyphox gyroscope buffers and build RPM trace.
2) Remove start/end regions using trim settings.
3) Find the longest stable contiguous segment.
4) Convert RPM deviation to FM around fixed carrier.
5) Write stereo PCM_24 WAV at 96 kHz (L == R).
6) Call wf_analyze.py / wf_core.py on generated WAV.
7) Save analysis plot and metrics text report.


Important note about "Mean frequency"
--------------------------------------
In the analysis plot, "Mean frequency" is the mean audio carrier frequency from
the synthesized WAV (default near 1000 Hz), not the platter rotation in Hz.

RPM still affects rotational interpretation/labeling in the analyzer.


Examples
--------
Default run:

    python phyphox_preprocessor.py "Gyroscope rotation rate 2026-04-06 12-02-36_SL1300GNo2.phyphox"

45 RPM run:

  python phyphox_preprocessor.py "Gyroscope rotation rate 2026-04-06 12-18-56_SL1300GNo1.phyphox" --rsp 2

33 family run (normalized to 33.3333333333):

  python phyphox_preprocessor.py input.phyphox --rpm 33

78 RPM run:

  python phyphox_preprocessor.py input.phyphox --rsp 3

Aggressive trimming (if start/end data is unreliable):

    python phyphox_preprocessor.py input.phyphox --trim-start-s 12 --trim-end-s 12 --min-stable-s 30


Troubleshooting
---------------
- "Input must be a .phyphox file"
  Use a phyphox XML export with .phyphox extension.

- "No gyroscope channels available"
  Confirm the recording contains gyrX/gyrY/gyrZ or gyr buffers.

- "Trim settings remove all data"
  Reduce --trim-start-s / --trim-end-s.

- Very short stable segment
  Lower --min-stable-s or adjust --stable-factor.

- LaTeX/doc issues
  These do not affect preprocessing or analysis outputs.


Batch file usage
----------------
If using Run_phyphox_preprocessor.bat, ensure the filename in that batch file
matches an existing .phyphox file in the folder.


License and standards note
--------------------------
The preprocessor feeds data into the existing standards-oriented metric engine
in wf_core.py. Compliance-quality conclusions still depend on the full
measurement chain (sensor quality, mounting, calibration, and procedure).