Shinytone: an introduction

An open-source tool for citation tone research across tone languages, integrating the full citation-tone analysis workflow into one interactive app.

Designed for phoneticians, typologists, fieldworkers, and students working on lexical tone production.

🌱 Created by Chenzi Xu & Cong Zhang · github.com/chenchenzi/citationtone_hub

🔓 Open source 💻 Runs in your browser 🆓 Free, no install 🔁 Reproducible

Why Shinytone?

A cross-linguistic review of 136 citation-tone studies across 129 tonal varieties of China found that methodological choices diverge at almost every step, limiting how well tone inventories can be compared within and across languages.

📈

Inconsistent f0 handling

f0 (the primary acoustic correlate of tone) is measured, normalised, and reported differently across studies.

👥

Small speaker samples

Many descriptions rest on very few speakers, limiting how far their tone inventories generalise.

🔍

Low transparency

Analytical decisions and procedures are often under-documented, so studies are hard to reproduce.

🧩

Limited comparability

These divergences make tone inventories difficult to compare within and across languages.

Issues documented in our cross-linguistic methodological review: Xu & Zhang (2024), JASA. Shinytone turns its recommendations into one transparent, reproducible pipeline.

Tone & terminology

A brief orientation to the linguistic notions Shinytone is built around.

📖 What is tone?

A tone language uses pitch contrastively at the lexical level: the same string of consonants and vowels can map to different words depending on the pitch pattern with which it is produced.

“A language is a tone language if the pitch of a word can change the meaning of the word.”

Yip (2002), Tone, p. 1.

Definitions span seventy years of typology and theory: Pike (1948); Hyman (2006); Yip (2002).

🎙️ Citation tones

A citation tone is the pitch shape a word takes when it is pronounced in isolation, away from the influence of neighbouring words, sentence intonation, or discourse context. This makes it the cleanest starting point for studying a language’s tonal contrasts.

Shinytone is designed for this use case: controlled recordings of single words or short syllables, one tone category per token, multiple speakers and repetitions.

🌊 Pitch vs. f0

Strictly speaking, Shinytone analyses f0 (fundamental frequency): the physical property of a voiced sound, measured in Hertz. Pitch is its perceptual correlate: how high or low a listener hears the sound.

We say pitch informally (rising pitch, falling pitch), but every measurement, plot, and model output is f0 in Hz, or its by-speaker normalisation in semitones or z-scores.

What you can do

Two complementary workspaces, from audio recordings to pitch-contour analysis.

Pitch Measurement F0 Processing tab

Go from raw .wav files to clean f0 contours, ready for the analysis pipeline.

🌊

Extract

f0 from audio with wrassp, or import Praat .Pitch / .PitchTier files.

🔧

Correct

Listen, inspect the waveform, and fix extraction errors frame by frame.

Pitch Contour Analysis F0 Analysis tab

Run the full citation-tone analysis pipeline on f0 measurements (CSV).

🎨

Visualise

Plot f0 contours by tone, with faceting and normalisation.

🔎

Inspect

Flag octave jumps, outliers, and tracking errors.

📊

Model

Polynomials, GCA, and GAMM with tonal defaults.

📋

Summarise

Convert contours into Chao tone numerals (1–5).

Pitch Measurement F0 Processing tab

Go from raw .wav files to clean f0 contours, ready for the analysis pipeline.

🌊Extract

Extract f0 contours from .wav using the wrassp R package, or import pre-computed Praat .Pitch / .PitchTier files.

🔧Correct

Review and correct extraction artefacts by listening, inspecting the waveform, and editing individual frames (halve, double, interpolate, smooth, manual entry).

▸ Click a step to preview its screenshot.

Pitch Contour Analysis F0 Analysis tab

Run the full citation-tone analysis pipeline on f0 measurements (CSV).

🎨Visualise

Plot f0 contours by tone, with speaker faceting and normalisation (z-score / semitone).

🔎Inspect

Flag likely f0 artefacts (octave jumps, outliers, tracking errors) via z-scores and jump detection.

📊Model

Per-token polynomials, Growth Curve Analysis (GCA), and Generalised Additive Mixed Models.

📋Summarise

Convert tone contours into Chao tone numerals (1–5) for cross-language comparison.

▸ Click a step to preview its screenshot.

Recommended workflows

Four pipelines: the output of each chains into the input of the next.

1

Pitch extraction F0 Processing

🎤 .wav➔ 📊 .Pitch (Praat)or 📊 pre-extracted f0 .csv➔ F0 Extraction (+ metadata)➔ 📊 f0 + metadata .csv

2

Pitch-tracking quality check F0 Analysis

📊 f0 .csv➔ Normalise (optional)➔ Visualise➔ Inspect➔ 📊 .csv with flags

3

Pitch-tracking correction F0 Processing

🎤 .wav+ 📊 .csv with flags➔ F0 Correction➔ 📊 cleaned f0 .csv

4

Contour modelling & summary F0 Analysis

📊 clean f0 .csv➔ Normalise➔ Model➔ Summarise➔ 📋 coefficients / Chao numerals

Highlights

Beyond bundling existing tools: Shinytone’s methodological contributions.

01

🧩 The whole pipeline, one tool

From raw recordings to publication-ready models and Chao numerals: extraction, screening, correction, normalisation, modelling, and summary in one consistent environment, instead of juggling Praat scripts, spreadsheets, and ad-hoc R code.

02

🔎 A new screen for f0 irregularities

Three complementary layers: speaker-level extreme-value (max / min) z-scores, token-level median/MAD z-scores by speaker × tone, and sample-level frame-by-frame jump, octave, and carryover checks with median-aware flag placement, catching halving/doubling, stray frames, and whole-contour shifts.

03

🎧 f0 correction by ear and eye

Every flagged token links back to its audio: listen, read the waveform, and repair individual frames (halve, double, interpolate, smooth, manual entry). Every edit is written to a downloadable log, so quality control is automatically documented and reproducible rather than silent.

04

📐 Comparative Chao tone numerals

Automated conversion of modelled contours into the Chao (1930) 1–5 tone letters, with the reference-line and interval-based methods shown side by side, so the final summary is a transparent, well-justified decision rather than a black-box output, and numerals can always be adjusted to preserve phonetic contrasts.

Shinytone as an R package

Everything the app does is also available as a scriptable, reproducible R package.

shinytone · v0.1.1 · GPL (≥ 3)

📘 Documentation
💻 Source on GitHub

# install from GitHub
remotes::install_github("chenchenzi/citationtone_hub")

# launch the Shiny app locally
shinytone::run_app()

Same app, no limits. run_app() serves the exact interface,
            but on your own machine: no upload-size cap, memory ceiling, or session timeout. Ideal for
            large-scale datasets and recordings that never leave your computer.

normalise_f0()

Per-speaker f0 normalisation in semitones, z-scores, or ERB.

inspect_f0()

Per-token z-scores plus sample-level jump detection.

fit_gca() / fit_gamm()

Growth-curve and GAMM models with citation-tone defaults.

contour_to_chao()

Normalised contour → Chao (1930) 1–5 tone-letter notation.

Open, free, and reproducible

Lowering the barriers to rigorous, reproducible tonal analysis.

🔓Open source. Every line is on GitHub under an open licence (GPL ≥ 3), free to inspect, reuse, and extend.
💻No barriers. Runs in any browser with no install or coding, or install it locally as an R package.
🧩Built on open tools. R, Shiny, and open phonetics libraries (wrassp, rPraat, praatpicture).
🔁Reproducible. One documented pipeline; export the underlying R code for every plot and model.
🔒Private by design. Uploads are processed only in transient session memory, never stored or shared.
📚Grounded & citable. The analysis methods we preset (f0 normalisation, modelling, and Chao conversion) follow our peer-reviewed methodological review (Xu & Zhang, 2024, JASA).

GitHub repository · 📄Methodology paper (JASA 2024) · 👥Chenzi Xu & Cong Zhang