# Suswara design

Created 2026-11-17 · Updated 2026-11-18

Companion [requirements and learning path](suswara-requirements.md)

## Ear-training objectives and design rules

The learner should be able to hear a pitch change, connect a sound to its swara relative to Sa, and reproduce a short pattern by ear. Set an audible, comfortable tonic first. Use the visual cues to learn the relationship, then check whether the learner can hear or sing it with the screen out of view.

### Practice sequence

1. **Listen and label.** At Single speed, hear a swara as its tile is marked. Say or sing its name back. Repeat a short phrase until the motion between notes sounds familiar.
2. **Listen without looking.** Play the phrase again with the screen out of view. Name the notes or the direction of the pitch change before checking.
3. **Echo and adjust.** Hear the reference, wait for the short tone to finish, then sing. Check the pitch meter, adjust once, and try again by ear. With the drone on, use headphones to reduce bleed into the mic.
4. **Check transfer.** Use blind higher/same/lower trials and repeat the phrase in a comfortable new key. Track recognition by ear and how reliably the learner can reproduce the relative intervals.

### Visual and interaction rules

| Cue | Rule |
| --- | --- |
| Relative pitch | Use one hue with darker low notes and lighter high notes. Base lightness on semitone distance from Sa or Do. The same note has the same fill in both rows, including at the upper Sa turnaround. Keep swara text and frequency readable at every shade. |
| Sounding note | Change all text on the sounding tile to dark copper, including the swara, frequency, and optional keyboard name. Keep its size, weight, position and pitch tint consistent. Check both active and resting text for at least 4.5:1 contrast across the pitch tints. Put the frequency on its own line below the title. In Carnatic exercises, hide keyboard names on the tiles by default and reveal them on a separate line with Show keyboard notes. Keep the keyboard tuning controls available. Mark only the sounding tile, clear it in rests and on stop, and keep keyboard focus visually distinct. Use the audio schedule as the source of timing and expose the current tile to assistive technology. |
| Sarali layout | Show the ascending and descending tiles together, without visible direction headings. Keep accessible group labels. Place tuning and playback controls below the tiles, with one Play action and the option to tap an individual swara. |
| Phrase and timing | Play the full first Sarali Varisai in Mayamalavagowla. Sound upper Sa twice as separate attacks, once in each row. Restart at lower Sa when looping. Keep the selected shruti and speed consistent throughout a pass. |
| Practice controls | Default to middle C as a familiar piano reference and let the learner choose or capture a comfortable Sa. Share one drone across panels. Keep it independent of the exercise so the learner can toggle it while notes play. |
| Ear-only checks | Keep blind identification trials free of pitch-dependent tint, tile highlights, or answer text until the learner responds. For mic practice, distinguish the target from the detected swara and give a clear raise/lower cue. |

Pitch and lightness have been associated in listening experiments. That supports trying the visual mapping as a practice cue. The study did not measure long-term swara learning. Judge whether the cue helps by checking recognition and reproduction after it is removed. [Marks, 1987](https://pubmed.ncbi.nlm.nih.gov/2958587/)

## Experience

A single responsive screen with four jump links. Explore has a movable tonic, octave and scale picker, tappable note tiles, two comparison selectors and a shared waveform plot. Train presents only the prompt until the learner answers. Match pairs a Sa drone with on-demand feedback for a selected note. Learning Path maps the progression and daily routine. Text equivalents carry the information conveyed by color and chart positions.

## Pitch model

Pitch is the perceived highness or lowness of a sound. For these pure tones it follows the frequency, the number of cycles per second. Real voices and instruments also contain harmonics that shape timbre. The waveform uses equal amplitudes, independent of pitch. It shows cycles over time, with two lanes so overlapping waves remain legible.

- Base frequency for MIDI note m is 440 × 2^((m−69)/12). The prototype accepts every chromatic tonic in octaves 0–8. For example, A3 is 220 Hz and A4 is 440 Hz.
- An interval measures a frequency ratio. An octave doubles frequency. In 12-tone equal temperament, one semitone is 100 cents and multiplies frequency by 2^(1/12), about 1.05946. The same semitone spans about 13.08 Hz above 220 Hz and 26.16 Hz above 440 Hz. Signed cents = 1200 × log₂(B/A).
- Movable Do major and the straight-note Shankarabharanam approximation share offsets 0, 2, 4, 5, 7, 9, 11, 12. Mayamalavagowla uses 0, 1, 4, 5, 7, 8, 11, 12. Carnatic scale degrees are relative to Sa. The 12-position keyboard grid is a teaching approximation. Carnatic has 16 traditional swara names for 12 conventional positions because some labels share nominal positions. Raga identity also depends on phrases, gamaka and context. The mock's synthesized exercise is a straight-note echo guide.
- A constant-duration view shows faster oscillation for higher pitches. An adaptive view sets the window to about three A cycles so the ratio remains readable across registers. Fixed duration is available to observe how transposing changes the number of cycles.

## Implementation decisions

**Data and ownership.** Browser-local session state holds tonic, scale, two comparison offsets, quiz and microphone state. Frequencies are derived from note coordinates. Each quiz trial captures its starting frequency and randomized direction, so replay is consistent. There are no network calls or stored audio. A new playback replaces scheduled playback. The microphone requires explicit activation. The analyser estimates a periodic fundamental from short sample windows. Quiet or unreliable frames show a neutral result. Feedback is intended for isolated sustained humming, with playback paused and headphones useful to limit leakage. In Match modes the voice estimate is compared with the selected practice target in its displayed octave. Analytics and licensed recordings would be separate product decisions.

**Expo path.** The local Tourzen Mobile package manifest shows Expo Router, React Native and react-native-svg. Reuse that general routing and chart stack in a standalone app. Split into typed pitch math and lesson definitions, UI routes, and an audio interface for reference tones, scheduled phrases, drone and microphone PCM. Evaluate generated tone buffers and expo-audio playback for the first native spike. Verify live microphone PCM availability and audio session behavior on the SDK selected for Suswara before choosing a native capture library. Test iOS and Android permission denial, interruptions, headphones, latency, accessibility, and low-frequency playback before enabling the matcher by default.

```mermaid
flowchart LR
    Controls --> Model[Pitch math and lesson definitions]
    Model --> Charts[Waveform and interval ruler]
    Model --> Audio[Reference playback and drone]
    Mic[Opt-in microphone] --> Estimate[Steady fundamental estimate]
    Model --> Feedback[Signed pitch feedback]
    Estimate --> Feedback
```

## Delivery sequence

| Stage | Deliverable | Exit evidence |
| --- | --- | --- |
| Wheel | Local browser mock and research-backed learning map | Known ratios and scales, mobile layout, playback scheduling, hidden-answer quiz, microphone stop and denial handling. |
| Skateboard | Expo device spike and teacher-reviewed lessons | iOS and Android checks, consistent reference audio, validated rough pitch estimator, permission and lifecycle tests. |
| Scooter | Guided practice history and selected recordings | Transfer checks with readings hidden, validated lesson order and licensing, learner feedback. |

## References

- [UNSW Music Acoustics](https://www.phys.unsw.edu.au/music/notes.html)
- [Carnatic gamaka analysis](https://archives.ismir.net/ismir2017/paper/000082.pdf)
- [Web Audio interaction and scheduling](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Best_practices)
- [Browser microphone permissions](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia)
- [Expo Audio](https://docs.expo.dev/versions/latest/sdk/audio/)

## Prototype verification

Local headless Chrome checks passed at a 320 px viewport. They covered the A3 octave ratio, semitone Hz gaps at A3 and A4, interval reversal, chromatic mode, playback scheduling and stop, drone, and quiz scoring. The pitch estimator was tested with synthetic harmonic signals from 79 to 720 Hz and with silence. A synthetic microphone session verified capture and track release. Permission denial was simulated. Physical microphone accuracy, acoustic output on phones, and native iOS and Android behavior remain unverified.

## Live shruti and swara practice design

The practice panel has three modes. **Match Sa** measures against the current tonic and enables **Use hum as Sa** when a stable reading is available. **Follow voice** chooses the scale degree nearest the detected pitch in cents. **Match a swara** lets the learner select a target and advance one step at a time. Detected and intended tiles carry visible text and distinct styling. The meter follows the target in Match modes and the nearest degree in Follow mode. Signed cents show the size and direction of error. The display uses ±15 cents as a prototype tolerance for sustained straight notes, with the marker clamped at ±100 cents and exact values still displayed.

A captured Sa supplies the actual session reference frequency. The tonic and octave selectors show the nearest keyboard note, and the reference label identifies a captured Sa. The same frequency feeds audio, scale tiles and plots. Selecting a different keyboard tonic or octave clears the captured tuning. The tracker searches the displayed tonic-to-octave scale. Below or above that range it highlights the nearest endpoint and shows range guidance. When Chromatic is selected, the strip shows all 13 positions. Weak or unstable audio and reference playback clear the reading. Mic use remains local and optional. On-device validation with real voices precedes any reliance on the reading for native practice.

Chrome regression checks at 320 px passed for the new controls. Simulated voice readings verified exact Sa capture and keyboard reset, Ga₃ detection, a distinct Ma₁ target, signed raise/lower cues, progression to Pa, and clearing the highlight when the reading is lost. Physical microphone and singing tests remain open.

The practice and explorer pickers share the same keyboard tonic and octave. The practice panel shows the active reference, including whether Sa was captured. A steady hum in Match Sa shows the closest 12-tone keyboard note and its offset independently of the measured error against the active Sa. An explicit **Use keyboard Sa** button clears capture even when the nearest keyboard note and octave are already selected.

Practice swara taps play the target immediately. Short reference tones and the continuous drone have separate playback state. The pitch tracker gates only on the short tones. The drone runs quietly, and microphone input requests browser echo cancellation. A headphone cue remains visible because speaker bleed can still dominate a single-pitch estimate. Capturing a new Sa requires turning off the drone to reduce accidental capture of the reference itself.

## Pitch Explorer playback cues

For a scale, one ordered set of note offsets supplies both the oscillator frequencies and the card identifiers. Schedule each tone on the Web Audio clock and use the same start and end times to highlight its card, with the browser audio output timestamp when available. Match cards by offset, so the upper tonic remains distinct. Stop or a settings change cancels the audio sequence and clears its highlight. Use a fixed 80 BPM exercise pulse with subdivisions of 1, 2 and 4 notes per beat. These are prototype pacing choices, independent of raga and tala.

C4 is the initial keyboard tonic in both panels. Octave 4 is labeled as the middle C register. Display the name “middle C” only when the keyboard reference is C4, so a different tonic or a captured hum retains its own label and frequency.

Repeat playback schedules one additional cycle shortly before the current cycle ends. It keeps a rolling two-cycle highlight schedule on the same audio clock. All explorer exercises use the same repeat setting. Turning repeat off clears the exercise timer, scheduled notes and highlight while keeping the drone. A separate drone toggle controls the same Sa in both panels and works during playback. Changing the tonic retunes an active drone. Stop sound clears both audio paths.

The sarali starter takes the eight ascending Mayamalavagowla offsets followed by their full reverse. This gives 16 discrete attacks, with separate upper Sa attacks at notes 8 and 9. Each loop schedules the same full pattern at the same shruti. [Carnatic Circle lesson notation](https://carnatic-circle.com/carnatic-lessonsnotes/varisais/sarali-varisai/)

Selecting Sarali Varisai 1 displays Arohanam and Avarohanam together with one playback action beneath them. Other presets show one scale row. The current scale presets all use a symmetric step set, so reversing a copy correctly produces their descent. Future ragas with different ascending and descending patterns will need explicit sequences. Sarali keeps its separate Mayamalavagowla lesson pattern, including both upper Sa attacks.

The two directions have separate tappable card rows. Each playback event is paired with the card in its own row. Mayamalavagowla sarali moves the highlight from the final Sa′ card in the ascending row to the first Sa′ card in the descending row, making the two equal-pitch attacks visible.

### Aakaram practice sound

Pitch Explorer offers **Pure tone** and **Aakaram (ā)**. Both use the same note frequencies, timing and tile cues. The Aakaram reference adds vowel-like harmonics to the oscillator at the exact written fundamental. It is a synthesized cue for singing the phrase on one vowel. The swara labels stay on the tiles. The independent drone, interval comparisons, and blind drills keep their pure-tone sound.

First sing the phrase with swara names over the reference. Then repeat it on ā, keeping the pitch and pulse the same. Use a teacher's rendition to hear connected vowel phrasing and vocal tone. [Acharyanet practical exercises](https://www.acharyanet.com/practical-exercises-in-carnatic-music/)
