ViperTuner Manual

Home Screen

Figure 1.1: Home screen

The home screen provides quick access to start a new tuning session, resume a previous session, or browse saved tuning data.

Figure 1.2: Home screen controls

Method Selection

Figure 2.1: Choose tuning method

Choose how to generate the tuning curve for your piano. Each method provides different levels of customization.

Figure 2.2: Available tuning methods

Classic Setup

Figure 3.1: Classic mode setup

Classic mode provides a quick path to tuning with minimal configuration. The only setting is the A4 reference pitch.

Figure 3.2: Classic setup controls

Note: Classic mode uses a generic inharmonicity model that works reasonably well for most pianos but won't be as accurate as Custom or Measure modes for your specific instrument.

Custom Setup

Figure 4.1: Custom mode setup

Custom mode lets you select your piano type and configure the tuning parameters without measuring inharmonicity.

Figure 4.2: Custom setup controls

Custom Finalization

Figure 5.1: Custom finalization overview

After selecting your piano type, the finalization screen lets you optimize the tuning curve and preview the results.

Generated Curve

Figure 5.2: Finalization with generated curve

Click "Generate Curve" to compute the optimal tuning based on your settings. The charts show:

• Tuning Curve — Target cents offset from equal temperament across the keyboard
• Inharmonicity — The B coefficient (string stiffness) for each note
• Octave Stretch — How much each octave is stretched from pure 2:1 ratio
• Interval Deviations — How temperament intervals compare to just intonation

Tip: Click any chart to expand it to fullscreen for detailed viewing.

Expanded Chart Views

Click any chart to view it fullscreen with enhanced detail. Each chart type provides specific insights:

Tuning Curve (Expanded)

Figure 5.2a: Tuning curve expanded view

Shows the target cents offset from Equal Temperament across all 88 notes (A0 to C8). Key elements:

• Blue cloud region — The range of valid tuning positions based on coincidence settings (2:1 pure octaves to 6:3 stretched octaves)
• Green/blue curve — The optimized tuning curve (green = model-based, blue = measurement-based)
• Yellow dashed line — Break point location (first unwound string)
• White dashed line — A4 reference position

The characteristic Railsback shape appears: bass notes tuned progressively flat, treble notes progressively sharp, with the curve crossing zero near the temperament octave.

Inharmonicity (Expanded)

Figure 5.2b: Inharmonicity coefficient expanded view

Displays the logarithm of the B coefficient (string stiffness) for each note. The B value determines how much a string's partials deviate from pure harmonic ratios—critical for understanding why piano octaves must be stretched.

• Gray dots — Model-based values (from piano archetype)
• Blue dots — Directly measured values
• Green dots — Interpolated between measurements
• Yellow dashed line — Break point (inharmonicity jumps here as strings transition from wound to plain steel)

Higher B values (less negative log) mean more inharmonicity. The break point typically shows a discontinuity where wound bass strings transition to plain steel treble strings.

Octave Stretch (Expanded)

Figure 5.2c: Octave stretch expanded view

Shows how much each octave interval is stretched beyond the pure 2:1 ratio. This visualization helps understand the tuning's character and verify smooth progression.

• White line with dots — Actual calculated stretch for each octave
• Blue cloud region — Valid stretch range based on coincidence bounds
• Colored dashed lines — Center positions for different coincidence types:
  • Purple: Octave coincidences (2:1, 4:2, 6:3)
  • Orange: Twelfth coincidences (3:1, 6:2)
  • Teal: Double octave (4:1, 8:2)
  • Yellow: Double octave + fifth (6:1, 12:2)

A well-optimized curve stays within the cloud and progresses smoothly from bass to treble. The stretch typically increases in the treble to compensate for increasing inharmonicity.

Interval Deviations (Expanded)

Figure 5.2d: Interval deviations expanded view

Visualizes the selected temperament's intervallic character—how major thirds, minor thirds, and perfect fifths deviate from pure just intonation for each of the 12 root notes (C through B).

• Red bars — Major third deviation (positive = wider than just 5:4)
• Green bars — Minor third deviation (negative = narrower than just 6:5)
• Blue bars — Perfect fifth deviation (typically near zero)
• Reference lines:
  • Dark red dashed: Pythagorean major third (~22¢ wide)
  • Light red dashed: Equal temperament major third (~14¢ wide)
  • Green solid: Just intonation (0¢ reference)
  • Blue dashed: ET perfect fifth (~2¢ narrow)
  • Green dashed: ET/Pythagorean minor third positions

In Equal Temperament, all bars are uniform. Historical temperaments show varied key colors—some keys with purer thirds (bars closer to zero), others with wider thirds (bars extending toward Pythagorean).

Controls

Figure 5.3: Finalization controls

Temperament Selection

Figure 5.4: Temperament selection panel

The temperament selector determines how intervals are distributed across the keyboard. This affects the "color" of different keys.

Note: For standard modern piano tuning, Equal Temperament is recommended. Historical temperaments like Kirnberger III or Vallotti provide distinct key colors suited for Baroque and Classical repertoire.

Interval Deviations Chart

Figure 5.5: Interval deviations from just intonation

Advanced Settings

Figure 5.6: Advanced optimization settings

The Advanced panel provides fine-grained control over the optimization algorithm. Expand it to access these settings:

Coincidences

Select which interval coincidences the optimizer should target. Piano strings have multiple harmonic partials, and different coincidences create different tonal characters.

• Full ET — All coincidences enabled (modern equal temperament standard)
• Historical — Emphasizes fifth-related coincidences (6:3, 6:1, 12:2)
• Octaves Only — Only pure octave coincidences (2:1, 4:2)

Individual coincidences can be toggled: ● Pure octave (2:1, 4:1, 4:2, 8:2), ● Fifth-related (6:3, 3:1, 6:2, 6:1, 12:2)

Beat Rate Smoothing

Enable smoothing for specific intervals to create progressive beat rates. When enabled (●), the optimizer ensures these intervals have gradually increasing beat rates as you move up the keyboard.

• M3 — Major thirds (important for melodic smoothness)
• P5 — Perfect fifths (critical for harmonic structure)
• M6 — Major sixths (affects key color)
• M10 — Major tenths (compound thirds)

Volume Influence

Controls how much the measured harmonic volumes affect optimization. At 100% (Volume-weighted), louder partials have more influence. At 0% (Uniform), all partials are weighted equally.

• Center Pull — How volume weighting affects the pull toward coincidences
• Beat Smoothness — How volume weighting affects beat rate smoothing

Voicing Adjustments

Fine-tune the stretch curve in specific registers. Positive values brighten (more stretch), negative values darken (less stretch). The five sliders cover:

• Low Bass / High Bass — Adjust bass stretch below the break point
• Break→A4 / A4→A6 / A6→C8 — Adjust treble stretch in three zones

Use the Reset button to return all voicing adjustments to zero.

Measure Setup

Figure 6.1: Measure mode setup

Measure mode analyzes your piano's actual inharmonicity by recording each note. This produces the most accurate tuning curve tailored to your specific instrument.

Figure 6.2: Measure setup controls

Configure measurement options before beginning:

• A4 Reference — Set concert pitch (default 440 Hz)
• Start Measuring — Begin the measurement workflow

Note: Measurement takes 3-5 minutes for the full keyboard. You can measure fewer notes for a quicker result, but accuracy improves with more data points.

Measurement

The measurement screen guides you through recording your piano's notes to capture inharmonicity data. The process has four states: preparation, recording, processing, and results.

Pre-Recording

Figure 6A.1: Pre-recording state

Before recording begins, select your measurement protocol and prepare the microphone.

Figure 6A.2: Pre-recording controls

Recording

Figure 6A.3: Recording in progress

During recording, play each note in the selected protocol from low to high. The phase-space visualization shows audio activity and helps confirm the microphone is capturing sound.

Figure 6A.4: Recording controls

Tip: Play each note firmly and let it ring for 1-2 seconds before moving to the next. The algorithm detects note onsets automatically—you don't need to time your playing precisely.

Results

Figure 6A.5: Analysis results

After processing, the results screen displays a summary of the detected notes and measured inharmonicity curve.

Figure 6A.6: Results controls

Note: If coverage is below 80%, consider re-recording. Missing notes in the bass or around the break point can reduce curve accuracy.

Measured Finalization

Figure 7.1: Measured finalization overview

After measuring your piano, the finalization screen shows comprehensive analysis of the measured data and generated tuning curve.

Generated Curve

Figure 7.2: Finalization with measured data

The measured mode provides additional charts beyond custom mode:

• Before/After — Compare measured tuning state to generated targets
• Pre-Tuning State — Shows how flat/sharp each note was before tuning
• Work Required — Highlights notes needing the most adjustment

Tip: Click any chart to expand it to fullscreen for detailed viewing.

Expanded Chart Views

Click any chart to view it fullscreen with enhanced detail. Measured mode includes all standard charts plus three measurement-specific charts:

Tuning Curve (Expanded)

Figure 7.2a: Tuning curve expanded view

Shows the target cents offset from Equal Temperament based on your piano's measured inharmonicity. The blue curve reflects your specific instrument's characteristics rather than a generic model. See Custom Finalization for element descriptions.

Inharmonicity (Expanded)

Figure 7.2b: Inharmonicity coefficient expanded view

Displays the measured B coefficient for each note. In measured mode, you'll see a mix of blue dots (directly measured notes) and green dots (interpolated between measurements). The actual break point location is determined from your measurements rather than estimated.

Octave Stretch (Expanded)

Figure 7.2c: Octave stretch expanded view

Shows calculated octave stretch based on your measured inharmonicity data. The cloud bounds and coincidence lines reflect your piano's actual string characteristics. See Custom Finalization for element descriptions.

Before/After Comparison (Expanded)

Figure 7.2d: Measured state vs target curve

Overlays the piano's current tuning state against the optimized target curve, showing exactly how much work is needed to achieve the target.

• Red curve with dots — Current (before) tuning state, smoothed through measured points
• Blue curve — Target tuning curve
• Orange dashed line — Estimated treble state (for unmeasured notes, assumes average deviation from target)
• Yellow dashed line — Break point

The vertical gap between curves at any point shows the cents adjustment needed for that note. A piano that's uniformly flat will show parallel curves; uneven tuning shows varying gaps.

Pre-Tuning State (Expanded)

Figure 7.2e: Original tuning state

Shows where the piano was before you started—the raw measured pitch of each note relative to Equal Temperament at your reference pitch.

• Red curve with dots — Measured pre-tuning state (smoothed trend line)
• Orange dashed line — Estimated treble continuation (for unmeasured notes)
• Zero line — Equal temperament at reference pitch
• Note count — Shows how many notes were directly measured vs estimated

This chart reveals the piano's condition: uniformly flat pianos show a horizontal line below zero; pianos with varying pitch show irregular curves. The break point often shows a discontinuity where string characteristics change.

Work Required / Deviation (Expanded)

Figure 7.2f: Tuning work required by note

Bar chart showing how many cents each note needs to be adjusted. Positive bars (above zero) indicate notes that are sharp and need to be lowered; negative bars (below zero) indicate flat notes needing raising.

• Green bars — Minimal work needed (<5¢ deviation)
• Yellow bars — Moderate adjustment (5-10¢)
• Orange bars — Significant adjustment (10-15¢)
• Red bars — Major work needed (>15¢)
• Hatched bars — Estimated (unmeasured notes assumed to have average deviation)

Use this chart to identify problem areas before you start tuning. Clusters of red bars indicate sections needing extra attention; isolated red bars may indicate individual problem strings.

Interval Deviations (Expanded)

Figure 7.2g: Interval deviations expanded view

Visualizes the selected temperament's intervallic character. See Custom Finalization for detailed element descriptions. Note: this chart shows the selected temperament's interval qualities, not the piano's current state—it's the same whether you choose Equal Temperament, Kirnberger III, or another temperament.

Controls

Figure 7.3: Finalization controls

Interval Deviations Chart

Figure 7.4: Interval deviations from just intonation

This chart visualizes the selected temperament's intervallic character—how major thirds, minor thirds, and perfect fifths deviate from pure just intonation for each root note. It reveals the "color" of different keys in historical temperaments (e.g., Kirnberger III has pure thirds in some keys and wider thirds in others), or shows the uniform distribution in Equal Temperament.

See the Custom Finalization section for detailed chart element descriptions.

Aural Setup

Figure 7B.1: Aural mode setup

Aural mode guides you through traditional temperament-setting techniques using your ears, with visual confirmation of coincident partials. Configure your piano and select a temperament sequence.

Figure 7B.2: Aural setup controls

Available Temperaments

• Equal Temperament — Standard 12-tone ET using M3 and M6 intervals with progressive beat rates (7→9→11→14 bps ladder).
• EBVT Victorian — Bill Bremmer's Equal Beating Victorian Temperament with 24 distinct key characters. Uses "copy, don't count" technique where only one beat rate (6 bps) is counted.

Figure 7B.3: Detailed temperament sequence information

Note: Tap the ? button on any temperament card to see the complete sequence of steps, expected beat rates, and checkpoints for that temperament.

Aural Temperament Workflow

Figure 7C.1: Aural temperament guided workflow

The aural temperament screen guides you through setting the temperament octave (F3-F4) using traditional interval techniques. Each step shows the coincident partials you need to observe.

Navigation Controls

Figure 7C.2: Navigation controls

Step Information

Figure 7C.3: Step instruction panel

Beat Rate Display

Figure 7C.4: Beat rate measurement and target

Beat Gauge

Figure 7C.5: Beat gauge for TUNE steps

On TUNE steps (like setting the F3-A3 major third), a beat gauge appears in the spectrum display. The yellow target marker shows where the beat rate should fall. Tune until the spectrum activity aligns with the yellow marker.

Verify Steps (Ladder Checks)

Figure 7C.6: VERIFY step for checking interval relationships

VERIFY steps check that your tuning is consistent. The classic "ladder check" verifies that M3 intervals beat progressively faster as you ascend: F3-A3 (~7) → A3-C#4 (~9) → C#4-F4 (~11) → F4-A4 (~14). If any interval sounds wrong, go back and adjust.

Help Modal

Figure 7C.7: Detailed help for the current step

Tap the help button to see detailed guidance for the current step, including technique tips and what to listen for.

Full Interface Overview

Figure 7C.8: Complete temperament interface

Workflow Phases (Equal Temperament)

Phase 1: M3 Ladder Foundation — Start with A4 reference (440 Hz), set A3 as beatless octave, then build the characteristic M3 ladder: F3-A3 (~7 bps), A3-C#4 (~9 bps), C#4-F4 (~11 bps), and verify F4-A4 (~14 bps).

Phase 2: M6s Descending + E4 — Use M6 intervals to fill in C4, E4, F#4, G#3, and D4. M6 intervals beat at approximately 8-12 bps in this range.

Phase 3: M3 Chain to Complete — Complete the chromatic scale using alternating M3 and M6 intervals: A#3, F#3, D#4, B3, and G3. Final check: play chromatic F3-F4.

Tip: The visual display shows coincident partials, but your ears are the final judge. Listen for the characteristic beat rate specified for each interval. The display provides confirmation but should not override what you hear.

Aural Octave Expansion

Figure 7D.1: Aural octave expansion overview

After setting the temperament octave (F3-F4), expand the tuning to the full keyboard using aural octave techniques. This phase uses partial matching to tune each octave while maintaining the character established in the temperament.

Navigation Controls

Figure 7D.2: Octave expansion navigation

Full Interface

Figure 7D.3: Octave expansion interface

Bass Register

Figure 7D.4: Bass register with multiple partials

In the bass register, multiple partials (P2, P3, P4, P6, P8) are displayed because low notes have rich harmonic content. Tune by matching these partials to the corresponding temperament notes:

• P2 — One octave above the fundamental
• P3 — Twelfth (octave + fifth) above
• P4 — Two octaves above
• P6 — Two octaves + fifth above
• P8 — Three octaves above

Tip: In the bass, inharmonicity causes higher partials to be progressively sharper. A "beatless" octave may actually have the upper note slightly flat to compensate. Listen for the smoothest overall sound rather than eliminating all beats.

High Treble Register

Figure 7D.5: High treble with fewer partials

In the high treble, only partials 1 and 2 are displayed because high notes have minimal harmonic content—the fundamental dominates. Treble tuning relies more on octave relationships with the temperament notes below.

Note: High treble notes (above C7) are difficult to tune aurally due to limited harmonic content. Many technicians use octave-and-a-half or double-octave checks, listening for smooth progression rather than perfect unisons. The visual display can help confirm pitch when partials are hard to hear.

Tuning Screen

Figure 4.1: Main tuning interface

Navigation Controls

Figure 4.2: Note navigation controls

Canvas Tap Zones

The spectrum canvas is divided into four tap zones for quick navigation without reaching for buttons.

Figure 4.3: Tap zones on the spectrum canvas

Note: A brief highlight appears when a zone is tapped.

Utility Controls

Figure 4.4: Utility controls around the tuning display

Cents Bar & Zoom

Figure 4.5: Cents bar with zoom control

Zoom Levels

Five zoom levels are available. The current level is shown on the right side of the cents bar (e.g., "3x"). The effect of zoom varies by visualization mode.

How Zoom Affects Each Mode

The cents bar always responds the same way: higher zoom = narrower displayed range (see table above). The visualization effect varies by mode:

Note: Zoom level is saved and restored between sessions.

Auto-Switch

Auto-switch automatically advances to the next (or previous) note when a strong signal is detected within ±65 cents of the adjacent note. Tap the note display to cycle through modes.

OFF

Figure 4.6a: Auto-switch disabled

Manual note selection only. The app stays on the current note regardless of what is played.

UP

Figure 4.6b: Auto-switch UP mode

When a note one semitone higher is struck, the display advances to that note. The right arrow button shows a blue highlight when this mode is active.

DOWN

Figure 4.6c: Auto-switch DOWN mode

When a note one semitone lower is struck, the display moves to that note. The left arrow button shows a blue highlight when this mode is active.

BOTH

Figure 4.6d: Auto-switch BOTH directions

Responds to notes struck in either direction. Both arrow buttons show blue highlights.

Visualization Modes

ViperTuner provides eight visualization modes, each optimized for different tuning scenarios. Use the prev/next viz buttons to switch between modes.

Spectrum

Figure 9.1: Spectrum mode

The primary tuning view. Displays the ZoomFFT spectrum as vertical bars spanning ±120 cents around the target pitch. A fisheye distortion magnifies the center region, making small deviations more visible while keeping the full range available.

How to use: Bring the spectrum peak to the center line. Left of center = flat, right = sharp. The indicator dot in the upper-right shows strike detection state: gray (waiting), yellow (attack detected), green (monitoring steady state). The cents bar below provides a numeric readout.

PitchZone

Figure 9.2: PitchZone mode

Designed specifically for pitch raises. The display is asymmetric: the left half shows how flat the note is (full 120-cent range), while the right half shows the overpull target zone (compressed to the safe overpull limit for the current note and string type).

Five color-coded bands appear on both sides. The principle: match the color. If the spectrum shows the note is in the "orange zone" on the left, overpull to the corresponding orange zone on the right. The white vertical line marks the maximum safe overpull limit (varies by note: ~12¢ for wound strings, 30-38¢ for unwound).

A magenta strike line appears at the moment of hammer impact, showing the initial pitch before settling. The info overlay (top-right) shows the overpull percentage and string type (wound/unwound).

How to use: Strike the note and observe where the peak lands on the left (flat) side. Raise pitch until the peak reaches the same color band on the right (overpull) side. The cyan center line is the final target—the pitch will settle there as the string relaxes.

Aural

Figure 9.3: Aural mode

Overlays multiple harmonic partials on a single spectrum view. Each partial (P1-P8) is rendered in a distinct color, showing where that partial's energy falls relative to its expected position. This visualizes the same relationships you listen for in aural tuning.

The toggle buttons along the top let you enable/disable individual partials. Button labels show the reference notes for checking coincident partials (e.g., for A4: P3 shows E5/E4 for octave checks, P4 shows D5/F4 for fourths/thirds). The beat rate display (top-right, large number) shows the measured beat rate in Hz, colored to match the highest enabled partial.

How to use: Enable the partials you want to compare and observe their spacing. The visual separation between partial peaks corresponds to the beat rate you hear—for example, an F3-A3 major third should show approximately 7 Hz separation between coincident partials. Use this to verify beat rates match your target temperament rather than to eliminate beats. A warning appears when zoom distorts the spacing—use zoom level 1 for accurate partial relationships.

Waterfall

Figure 9.4: Waterfall mode

A scrolling spectrogram that shows pitch stability over time. The current spectrum appears at the top and scrolls downward, building a history. Color intensity indicates magnitude (dark blue → cyan → green → yellow → red). A vertical white center line marks the target pitch.

The gamma-corrected color mapping (power 0.35) expands low-magnitude detail, making beat patterns visible as horizontal ripples in the display.

How to use: Watch for a stable vertical line through the history. Wavering or curves indicate pitch instability. This mode excels at showing whether a unison is holding pitch or drifting, and for spotting false beats from unstable strings.

Concentric

Figure 9.5: Concentric circles mode

Three colored circles move horizontally based on pitch deviation. Each circle has a different sensitivity:

• Outer (red-pink): ±120 cent range, locks within 5¢
• Middle (blue): ±50 cent range, locks within 2.5¢
• Inner (mint): ±25 cent range, locks within 0.5¢

When a circle is within its locking tolerance, it snaps to center and fades slightly. The innermost circle provides the finest precision.

How to use: First bring the outer circles to center (coarse tuning), then focus on the innermost circle for fine adjustment. When all three circles are locked at center, the note is within ±0.25 cents. A dashed vertical line follows the innermost circle for precise tracking. This mode works well for technicians who prefer non-numeric feedback.

Lissajous

Figure 9.6: Lissajous figure mode

Combines a 13-point Lissajous figure with a heterodyne phasor indicator. The Lissajous curve (green) distorts based on pitch deviation—when in tune, the figure appears as a clean, symmetric shape; when detuned, the figure becomes asymmetric and irregular. A white indicator dot on the curve shows the pitch direction.

The phasor dot (outer orbit) provides precise phase lock indication: green = locked (phase velocity near zero), yellow = close, red = far. A trail shows recent phase history. Cent markers around the circle (-100, -20, -10, -5, 0, +5, +10, +20, +100) provide scale reference.

How to use: Adjust pitch until the Lissajous figure becomes symmetric and the phasor dot turns green and holds position. A pulsing lock indicator appears at center when phase-locked. This mode is excellent for finding the exact center of a beat.

Quantum

Figure 9.7: Quantum orbital mode

An electron-orbital visualization where 300 particles occupy discrete energy levels. Orbital shells are positioned at Fibonacci-spaced cent intervals: 0, 0.38, 0.62, 1, 2, 3, 5, 8, 13, 21, 34, 55 cents from center. Particles don't drift smoothly—they jump between orbitals based on the spectrum energy at each interval.

The central nucleus glows orange when particles are distributed across orbitals (detuned), and bright green when particles cluster in the ground state (in tune).

How to use: Tune until particles collapse into the center. The discrete orbital jumps create a satisfying "snap to tune" effect—rather than watching a needle drift, you see particles suddenly drop into the ground state when close enough. This mode provides intuitive feedback without requiring you to interpret numbers or directions.

Railsback

Figure 9.8: Railsback curve mode

Displays the full 88-note tuning curve showing cents deviation from equal temperament. A0 to C8 spans the horizontal axis; vertical axis shows the target offset. The current note is highlighted with a yellow vertical line and a marker showing its target offset value.

Grid lines appear at octave boundaries (A notes) and at cent intervals. A green zero-line marks equal temperament. Shaded regions with diagonal hatching indicate notes without tuning data.

Classic mode note: In Classic mode, notes below A3 appear shaded because the bass is tuned using partial matching (P2, P3, P4, P6, P8 aligned to temperament notes) rather than direct pitch targets. This approach lets each piano's unique inharmonicity determine the bass stretch naturally—the curve varies by instrument. Only A3 and above show fixed cents values because treble inharmonicity is consistent across pianos.

How to use: This mode provides context rather than real-time feedback. Use it to understand the overall shape of your tuning curve, verify the stretch pattern makes sense, and see where the current note fits in the overall scheme. The curve shape should show characteristic bass flat / treble sharp stretch with smooth transitions.