wintergatan / tightinator

Automatic peak detection and timing analysis web app

Wintergatan Timing Data Analysis

aka THE TIGHTINATOR

The best peak detector in the tri-state area!

The community has long since clamoured for automatic peak detection and generation of timing data for the Wintergatan Marble Machine project. An offhand comment during the 2023 Community Meetup colalesced into this project.

View the live version

Run analysis at https://tightinator.fun

There is a 150M file size limit for upload, and working data will be removed after 7 days on disk.

Getting Started

The main.py file in the top-level of this repository is the best file for use locally and testing. The web/ directory contains the versions currently deployed onto the mcnulty.in endpoint.

The docker configuration is used for hosting and deploy, hence the internet host IP hard-coded in the gunicorn settings. This is to prevent header forging. You will need to edit a few sticking points if you want to use it for local development.

main.py will output help:

usage: main.py [-h] [-f FILENAME] [-o OUTPUT_FILENAME] [-t THRESHOLD] [-cf CUTOFF] [-c CHANNEL] [-d DOWNSAMPLE_RATE] [-cz CHUNK_SIZE] [-ex EXCLUSION] [-r FLOAT_PREC]
               [-l L_BESTSERIES] [-cp] [-b BPM_TARGET] [-bw BPM_WINDOW] [--work-dir WORK_DIR] [-w] [-x X_WIDE] [-y Y_HIGH] [-v]

Map transient times

options:
  -h, --help            show this help message and exit
  -f FILENAME, --file FILENAME
                        File to open.
  -o OUTPUT_FILENAME, --out OUTPUT_FILENAME
                        Filename to write output values to.
  -t THRESHOLD, --threshold THRESHOLD
                        Peak detection threshold. Works best 0.1 and above. Setting too high/low can cause misdetection. Defaults 0.1.
  -cf CUTOFF, --cutoff CUTOFF
                        The threshold below which the waveform should be cutoff for drawing. Does not affect anything outside the way the waveform is drawn, lowering below
                        0.01 will heavily decrease performance. Defaults 0.01.
  -c CHANNEL, --channel CHANNEL
                        Channel to get the waveform from. Defaults 1.
  -d DOWNSAMPLE_RATE, --downsampling DOWNSAMPLE_RATE
                        The downsampling used for drawing the waveform. Does not affect anything outside the way the waveform is drawn, lowering below 8 will heavily
                        decrease performance. Defaults 8.
  -cz CHUNK_SIZE, --chunk-size CHUNK_SIZE
                        Multiplied by sample rate, smaller chunks will increase run times. Defaults 8.4.
  -ex EXCLUSION, --exclusion EXCLUSION
                        Minimum distance between peaks in ms. Defaults 150.
  -r FLOAT_PREC, --precision FLOAT_PREC
                        Number of decimal places to round measurements to. Ex: -p 6 = 261.51927438. Defaults 6.
  -l L_BESTSERIES, --length L_BESTSERIES
                        The length of the series of most consistent beats. Defaults 100.
  -cp, --correlation    Decide whether correlation is used as a peakfinder. Defaults True.
  -b BPM_TARGET, --bpm-target BPM_TARGET
                        The target BPM of the song. Use 0 for auto. Defaults 0.
  -bw BPM_WINDOW, --bpm-window BPM_WINDOW
                        Window of BPM that should be visible around the target. Will be scaled to 75% target height if 0. Defaults 0.
  --work-dir WORK_DIR   Directory structure to work under.
  -w, --web             Get some width/height values from/ browser objects for graphing. Defaults false.
  -x X_WIDE, --x-width X_WIDE
                        Fixed width for graphs. Defaults 2000.
  -y Y_HIGH, --plot-height Y_HIGH
                        Fixed height for single plot. Defaults 1340.
  -v, --verbose         Set debug logging

Prerequisites

This project is written in Python 3, and uses pip to manage dependencies.

To install these libraries, run the following command:

pip install -r requirements.txt

Running with Docker

This project comes with a Dockerfile for the webapp implementation. There is also a compose file and a shell script for building and running the container in one go with docker-compose. If the container successfuly launches, you should be able to access it at http://127.0.0.1:5000 .

Standalone:

## Build and tag.
docker build . -t yanfett/wintergatan-data-analysis:latest

## Run the program.
# --network host      Use the host machine's loopback network. (127.0.0.1)
# -d                  Detach, runs the container in the background.
# -e DEBUG_MODE=True  Debug mode for the webapp. Remove or set to "False" to turn off.
docker run --network host -d -e DEBUG_MODE=True yanfett/wintergatan-data-analysis:latest

## Stop the program
docker stop <container name>

Compose:

## Build using the composefile.
docker compose build

## Run the program.
# -d                  Detach, runs the container in the background.
# -e DEBUG_MODE=True  Debug mode for the webapp. Remove or set to "False" to turn off.
docker compose run -d -e DEBUG_MODE=True wintergatan-data-analysis

## Stop the program
docker compose stop wintergatan-data-analysis

Contributing

Any contribution is welcome! Please branch your feature and create a Pull Request when ready for review.

Authors

So far written by Tom and Yan, with contributions from others! Thanks all! https://github.com/YanFett/Wintergatan_data_analysis/graphs/contributors

tightinator's Issues

view not showing correctly

You have truly done some good work with this. I however had a issue with the live version.
I confirmed that the height in advanced were making sense, it is at 1333, i also tried width 1080 and height 720. resulting in correct width and incorrect height.

this is what it shows me

https://wtg.mcnulty.in/result/c14ffe3b-3fce-4096-bf77-ed087f06091d/TheMoen_Sample1.csv

Issue:

Phase monitor

Hi,
with the use of multiple microphones spaced 45° apart or an Arduino based rotation sensor on the output, a live comparison based, e.g., on pyaudio would become possible.
This would give Information like the phase against a reference signal or the deviation to the optimal sinus output.

The results can help in identifying different origins of the variation as well as support the “tight” playing via a phase monitor displaying if acceleration or deceleration is required.

Before I would work on stuff like this, I would like to get an affirmation that it will be used.

Cheers
Dominik

Summary list not sorted

Ideally the list of previously run detections would be sorted from most recent first.

The filesystem correctly displays the files based on time but something happens between the filesystem and sending a display name/filename map over to be displayed.

summary-20230824-053342.html
summary-20230824-053404.html
summary-20230824-053751.html
summary-20230824-053802.html
summary-20230824-055714.html
summary-20230824-060211.html
summary-20230824-060824.html
summary-20230824-060908.html
summary.html

{display_name: '20230824-053342', filename: 'static/upload/cf26253f-18d5-4348-a52f-c00a6aa1955f/summary-20230824-053342.html'}
{display_name: '20230824-055714', filename: 'static/upload/cf26253f-18d5-4348-a52f-c00a6aa1955f/summary-20230824-055714.html'}
{display_name: '20230824-053802', filename: 'static/upload/cf26253f-18d5-4348-a52f-c00a6aa1955f/summary-20230824-053802.html'}
{display_name: '20230824-053751', filename: 'static/upload/cf26253f-18d5-4348-a52f-c00a6aa1955f/summary-20230824-053751.html'}
{display_name: '20230824-060824', filename: 'static/upload/cf26253f-18d5-4348-a52f-c00a6aa1955f/summary-20230824-060824.html'}
{display_name: '20230824-060908', filename: 'static/upload/cf26253f-18d5-4348-a52f-c00a6aa1955f/summary-20230824-060908.html'}
{display_name: '20230824-053404', filename: 'static/upload/cf26253f-18d5-4348-a52f-c00a6aa1955f/summary-20230824-053404.html'}
{display_name: '20230824-060211', filename: 'static/upload/cf26253f-18d5-4348-a52f-c00a6aa1955f/summary-20230824-060211.html'}

No end-to-end process monitoring

I check the site regularly for 200s (uptime) but there's no testing for making sure a file will be uploaded, the settings understood, the detection completed, and the graphs displayed.

Creating something to test this would involve using browser automation frameworks like https://www.selenium.dev/documentation/ and defining tests.

Huygen Physics Simulation

I've done some physics modeling of the Huygens chain drive with flywheel and governor, but it didn't account for the effects of varying power input. While it's a closed form equation and produces an RPM plot instantaneously, it's not detailed enough to reflect real world observations when tight timing is essential. An explicitly integrated approximation may prove to be more useful.

A physics simulation works well with an arbitrary choice of an input work function, including one modeling a "Martin." Moreover, the load function can be arbitrary, for instance simulating the actuation of marble gates. Experimenting with different flywheel weights, gear ratios, cranks, load profiles, etc can be done virtually before physical construction.

The question remains, however, of utility. Putting together a bespoke physics simulation is a substantial effort. I'd like to gauge the need for such a tool before committing to it.