PyTheory

https://pytheory.org/
Admin
PyTheory is a Python library for exploring music theory, composing multi-part arrangements, and...
Tokens:392,561
Snippets:2,866
Trust Score:1.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Initialize and Start LiveEngine

Source: https://pytheory.org/_modules/pytheory/live.html

Basic setup for the LiveEngine, including channel configuration and starting the engine.

```python
from pytheory.live import LiveEngine

engine = LiveEngine()
engine.channel(1, instrument="electric_piano")
engine.channel(2, instrument="bass_guitar", lowpass=800)
engine.channel(10, drums=True)
engine.start()  # blocks until Ctrl-C
```

--------------------------------

### REPL Welcome Screen

Source: https://pytheory.org/_sources/guide/repl.rst.txt

Example of the initial welcome screen displayed upon starting the REPL.

```text
   ♫  PyTheory REPL
   ════════════════════════════════════════

   try:  key Am          — set a key
         chords          — see its chords
         prog I V vi IV  — hear a progression
         drums bossa nova
         play_score      — hear it all

   help for all commands, quit to exit
```

--------------------------------

### start(port=None)

Source: https://pytheory.org/_modules/pytheory/live.html

Starts the live engine, initializing MIDI input and audio output streams.

```APIDOC
## start(port=None)

### Description
Starts the engine by opening the specified MIDI input port and initializing the audio output stream. This method blocks execution until the process is interrupted or stopped.

### Parameters
- **port** (int or str) - Optional - The MIDI port index or name to use. If None, the first available port is selected.
```

--------------------------------

### Install Live Dependencies

Source: https://pytheory.org/_sources/guide/live.rst.txt

Required installation for MIDI support.

```bash
$ pip install "pytheory[live]"
```

--------------------------------

### Initialize and Start LiveEngine

Source: https://pytheory.org/_sources/guide/live.rst.txt

Configure MIDI channels and start the engine to begin real-time synthesis.

```python
from pytheory.live import LiveEngine

engine = LiveEngine()
engine.channel(1, instrument="electric_piano")
engine.channel(2, instrument="bass_guitar")
engine.channel(10, drums=True)        # channel 10 = drums, per MIDI convention
engine.start()                        # blocks until Ctrl-C
```

--------------------------------

### start

Source: https://pytheory.org/api/live.html

Starts the engine.

```APIDOC
## start(port=None)

### Description
Starts the engine, opening MIDI input and audio output.

### Parameters
- **port** (int/str) - Optional - MIDI port index or name.
```

--------------------------------

### Install Optional Features

Source: https://pytheory.org/_sources/guide/quickstart.rst.txt

Install optional extras for MIDI input or Ableton Link synchronization.

```bash
$ pip install "pytheory[live]"   # MIDI input (python-rtmidi)
$ pip install "pytheory[link]"   # Ableton Link sync (LinkPython-extern)
```

--------------------------------

### Launch Interactive REPL

Source: https://pytheory.org/_sources/guide/cli.rst.txt

Start the music theory scratchpad with tab completion.

```bash
$ pytheory repl
```

--------------------------------

### Initialize LiveEngine

Source: https://pytheory.org/_modules/pytheory/live.html

Example usage for setting up the LiveEngine and configuring MIDI channels.

```python
        engine = LiveEngine()
        engine.channel(1, instrument="electric_piano")
        engine.channel(2, instrument="bass_guitar")
        engine.channel(10, drums=True)
        engine.start()
```

--------------------------------

### Initialize and Start Tuner

Source: https://pytheory.org/api/tuner.html

Programmatically start the tuner and access live readings.

```python
tuner = Tuner()
tuner.start()
while True:
    reading = tuner.reading  # dict or None, updated live
```

--------------------------------

### Install PyTheory

Source: https://pytheory.org/_sources/index.rst.txt

Use the uv package manager to install the library.

```console
$ uv add pytheory
```

--------------------------------

### Initialize and use the Tuner class

Source: https://pytheory.org/_modules/pytheory/tuner.html

Demonstrates basic instantiation and starting of the microphone-driven tuner.

```python
        tuner = Tuner()
        tuner.start()
        while True:
            reading = tuner.reading  # dict or None, updated live
```

--------------------------------

### Launch PyTheory Studio

Source: https://pytheory.org/_sources/guide/listening.rst.txt

Starts a local web application for visual transcription and playback.

```bash
$ pytheory studio
```

--------------------------------

### Initialize Keyboard Fretboards

Source: https://pytheory.org/api/chords.html

Create keyboard representations with varying key counts and starting notes.

```python
Fretboard.keyboard()            # 88-key piano
Fretboard.keyboard(61, "C2")    # 61-key controller
Fretboard.keyboard(25, "C3")    # 25-key mini controller
```

--------------------------------

### Install Ableton Link Dependencies

Source: https://pytheory.org/_modules/pytheory/live.html

Required installation command to enable Ableton Link synchronization features.

```bash
pip install pytheory[link]
```

--------------------------------

### Install PyTheory Plugin

Source: https://pytheory.org/guide/claude.html

Install the composing-with-pytheory plugin to enable music-related skills for Claude.

```bash
/plugin install composing-with-pytheory@pytheory
```

--------------------------------

### Serve Tuner via Browser

Source: https://pytheory.org/api/tuner.html

Start the local web server to access the strobe tuner interface.

```bash
$ pytheory tune --serve
# opens http://localhost:8123 — a strobe tuner page
```

--------------------------------

### start_recording()

Source: https://pytheory.org/_modules/pytheory/live.html

Initializes a new recording session, clearing previous events and setting the start timestamp.

```APIDOC
## start_recording()

### Description
Starts recording MIDI events. This method resets the internal event buffer and captures the current performance counter as the start time.

### Parameters
None
```

--------------------------------

### Start Live Session via CLI

Source: https://pytheory.org/_sources/guide/cookbook.rst.txt

Launches the TUI dashboard with Ableton Link enabled directly from the command line.

```bash
$ pytheory live --link
```

--------------------------------

### Initialize Keyboards

Source: https://pytheory.org/_sources/guide/fretboard.rst.txt

Initialize keyboard instruments with specific key counts and starting notes.

```pycon
>>> Fretboard.keyboard()             # 88-key piano (A0 to C8)
>>> Fretboard.keyboard(61, "C2")     # 61-key synth controller
>>> Fretboard.keyboard(49, "C2")     # 49-key controller
>>> Fretboard.keyboard(25, "C3")     # 25-key mini MIDI controller
```

--------------------------------

### Create a Musical Score

Source: https://pytheory.org/_modules/pytheory/rhythm.html

Example of setting up a multi-part arrangement with drums, chords, and instrument voices.

```python
        score = Score("4/4", bpm=140)
        score.add_pattern(Pattern.preset("bossa nova"), repeats=4)

        chords = score.part("chords", synth="sine", envelope="pad")
        lead   = score.part("lead",   synth="saw",  envelope="pluck")
        bass   = score.part("bass",   synth="triangle", envelope="pluck")

        for chord in key.progression("i", "iv", "V", "i"):
            chords.add(chord, Duration.WHOLE)

        lead.add("E5", Duration.QUARTER).add("D5", Duration.EIGHTH)
        bass.add("A2", Duration.HALF).add("D2", Duration.HALF)

        play_score(score)
```

--------------------------------

### Initialize Score and Progression

Source: https://pytheory.org/_sources/guide/sequencing.rst.txt

Basic setup for a score with a random chord progression.

```python
key = Key("A", "minor")
chords = key.random_progression(4)

score = Score("12/8", bpm=120)
for c in chords:
    score.add(c, Duration.DOTTED_HALF)
    score.add(c, Duration.DOTTED_HALF)
```

```pycon
>>> score.measures
4.0
```

--------------------------------

### Start tuner analysis

Source: https://pytheory.org/_modules/pytheory/tuner.html

Opens the microphone stream and initiates the background analysis thread.

```python
    def start(self):
        """Open the microphone and start analyzing."""
        import sounddevice as sd
        self._stream = sd.InputStream(
            samplerate=self.sample_rate, channels=1,
            blocksize=1024, device=self.device,
            callback=self._callback)
        self._stream.start()
        self._analyzing = True
        t = threading.Thread(target=self._analyze_loop, daemon=True)
        t.start()
        return self
```

--------------------------------

### REPL Prompt States

Source: https://pytheory.org/_sources/guide/repl.rst.txt

Examples of how the command prompt updates to reflect the current musical context.

```text
   pytheory[key=C | bpm=120]>

   pytheory[key=Am | bpm=140]>

   pytheory[key=Am | bpm=140 | drums=bossa nova]>

   pytheory[key=Am | bpm=140 | drums=bossa nova | →lead(saw)]>
```

```text
     key=Am | bpm=140 | drums=bossa nova | →lead(saw) rev=0.3 lp=2000
   ♫>
```

--------------------------------

### Get Prime Form

Source: https://pytheory.org/api/chords.html

Returns the canonical representation of the pitch class set, transposed to start on 0.

```python
>>> Chord([C4, E4, G4]).prime_form
(0, 4, 7)
>>> Chord([A4, C5, E5]).prime_form  # minor triad
(0, 3, 7)
```

--------------------------------

### Install PyTheory

Source: https://pytheory.org/_sources/guide/quickstart.rst.txt

Install the base package via pip.

```bash
$ pip install pytheory
```

--------------------------------

### System.__init__

Source: https://pytheory.org/_modules/pytheory/systems.html

Initializes a new musical system with specific tone names, degrees, and optional scale or ratio configurations.

```APIDOC
## System.__init__

### Description
Initializes a new musical system instance. Defines the tone names, degrees, and optional scale or ratio configurations for the system.

### Parameters
- **tone_names** (list) - Required - A list of tone names for the system.
- **degrees** (list) - Required - The degrees associated with the system.
- **scales** (dict) - Optional - A dictionary of scale definitions.
- **c_index** (int) - Optional - The index of the reference 'C' note.
- **period** (float) - Optional - The frequency ratio of one 'octave' (default 2.0).
- **ratios** (list) - Optional - Custom frequency ratios for the system.
```

--------------------------------

### Performance and Audio Tools

Source: https://pytheory.org/_sources/guide/cli.rst.txt

Launch specialized applications for tuning, recording, and MIDI synthesis.

```bash
$ pytheory tune --instrument guitar    # real-time terminal tuner
$ pytheory tune --serve                # browser strobe tuner + JS pitch stream
$ pytheory studio                      # browser: recording → sheet music
$ pytheory transcribe hum.m4a hum.mid  # recording → notes/MIDI
$ pytheory live --link                 # MIDI synth rig in the terminal
```

--------------------------------

### Install PyTheory Library

Source: https://pytheory.org/_sources/guide/claude.rst.txt

Install the core PyTheory Python package required for the plugin to execute music generation tasks.

```bash
uv pip install pytheory      # or: pip install pytheory
```

--------------------------------

### Install PyTheory Plugin for Claude Code

Source: https://pytheory.org/_sources/guide/claude.rst.txt

Commands to add the marketplace and install the PyTheory skill bundle into the Claude Code environment.

```bash
/plugin marketplace add kennethreitz/pytheory-skill
```

```bash
/plugin install composing-with-pytheory@pytheory
```

--------------------------------

### Initialize Instrument Fretboards

Source: https://pytheory.org/_sources/guide/fretboard.rst.txt

Create instances of various string instruments with their default or specific tunings.

```pycon
>>> Fretboard.ukulele()         # A4 E4 C4 G4  — re-entrant tuning
>>> Fretboard.banjo()           # open G (bluegrass) — 5th string is a high drone
>>> Fretboard.banjo("open d")   # open D (clawhammer, old-time)
>>> Fretboard.banjo("double c") # G C G C D (old-time)
>>> Fretboard.harp()            # 47 strings, C1 to G7 (concert pedal harp)
```

--------------------------------

### Start a drum pattern with MIDI clock

Source: https://pytheory.org/_sources/guide/live.rst.txt

Initializes a drum pattern and starts the engine, allowing it to sync with external MIDI clock sources.

```python
engine.drums("house", volume=0.5)
engine.start()
```

--------------------------------

### Get number of strings

Source: https://pytheory.org/_modules/pytheory/chords.html

Returns the count of strings on the fretboard.

```python
    def __len__(self) -> int:
        """Return the number of strings on this fretboard."""
        return len(self._tones)
```

--------------------------------

### Key.random_progression(length)

Source: https://pytheory.org/guide/scales.html

Generates a weighted-random chord progression starting on the tonic.

```APIDOC
## Key.random_progression(length)

### Description
Generates weighted-random progressions favoring common chord functions.

### Parameters
- **length** (int) - Required - The number of chords in the progression.

### Example
```python
progression = Key("C", "major").random_progression(4)
```
```

--------------------------------

### Create a Score and add Parts

Source: https://pytheory.org/api/rhythm.html

Demonstrates initializing a Score and adding multiple instrument parts with specific synth and effect configurations.

```python
score = Score("4/4", bpm=140)
lead = score.part("lead", synth="saw", envelope="pluck",
                  reverb=0.3, delay=0.25)
lead.add("E5", Duration.QUARTER).add("D5", Duration.EIGHTH)
bass = score.part("bass", synth="triangle", envelope="pluck")
bass.add("A2", Duration.HALF)
```

--------------------------------

### seventh

Source: https://pytheory.org/_modules/pytheory/scales.html

Builds a seventh chord starting from a specific scale degree.

```APIDOC
## Method: seventh(root: int = 0) -> Chord

### Description
Builds a seventh chord from the given scale degree (0-indexed). Returns a chord with the root, 3rd, 5th, and 7th.

### Parameters
- **root** (int) - Optional - The scale degree to use as the root of the seventh chord (default: 0).
```

--------------------------------

### triad

Source: https://pytheory.org/_modules/pytheory/scales.html

Builds a triad chord starting from a specific scale degree.

```APIDOC
## Method: triad(root: int = 0) -> Chord

### Description
Builds a triad starting from the given scale degree (0-indexed). Returns a chord with the root, 3rd, and 5th above it.

### Parameters
- **root** (int) - Optional - The scale degree to use as the root of the triad (default: 0).
```

--------------------------------

### LiveEngine Constructor

Source: https://pytheory.org/api/live.html

Initializes the real-time MIDI-to-audio engine.

```APIDOC
## LiveEngine(buffer_size=512, sample_rate=44100)

### Description
Initializes the real-time MIDI-to-audio engine.

### Parameters
- **buffer_size** (int) - Optional - Buffer size for audio processing (default 512).
- **sample_rate** (int) - Optional - Sample rate for audio output (default 44100).
```

--------------------------------

### Generate random chord progressions

Source: https://pytheory.org/_sources/guide/scales.rst.txt

Creates weighted-random progressions starting on the tonic.

```pycon
>>> key = Key("C", "major")
>>> [c.symbol for c in key.random_progression(4)]   # output varies
['C', 'Dm', 'F', 'C']
```

--------------------------------

### Recording Control Methods

Source: https://pytheory.org/_modules/pytheory/live.html

Methods to start and stop the recording of MIDI events.

```python
def start_recording(self):
        """Start recording MIDI events."""
        import time as _t
        self._record_events = []
        self._record_start = _t.perf_counter()
        self._recording = True
```

```python
def stop_recording(self):
        """Stop recording."""
        self._recording = False
```

--------------------------------

### Initialize a Score

Source: https://pytheory.org/_sources/guide/quickstart.rst.txt

Start a new musical arrangement using the Score class.

```python
from pytheory import Score, Key, Duration, play_score
```

--------------------------------

### Fretboard.__init__

Source: https://pytheory.org/_modules/pytheory/chords.html

Initializes a new Fretboard instance representing open strings.

```APIDOC
## Fretboard.__init__(tones: list[Tone], high_to_low: bool = False)

### Description
Initializes a Fretboard from a list of open-string Tone objects.

### Parameters
- **tones** (list[Tone]) - Required - List of Tone instances.
- **high_to_low** (bool) - Optional - Orientation of the fretboard. Defaults to False (low-to-high).
```

--------------------------------

### Get Normal Form

Source: https://pytheory.org/api/chords.html

Returns the most compact ascending arrangement of pitch classes.

```python
>>> Chord([C4, E4, G4]).normal_form
(0, 4, 7)
```

--------------------------------

### Create a ukulele Fretboard

Source: https://pytheory.org/_modules/pytheory/chords.html

Initializes a standard ukulele Fretboard with re-entrant tuning.

```python
    @classmethod
    def ukulele(cls, high_to_low: bool = False) -> Fretboard:
        """Standard ukulele tuning (A4 E4 C4 G4).

        Re-entrant tuning: the G4 string is higher than C4.
        """
        return cls._from_canonical(["A4", "E4", "C4", "G4"], high_to_low)
```

--------------------------------

### Part.__init__

Source: https://pytheory.org/_modules/pytheory/rhythm.html

Initializes a new musical part with specific synthesis, effect, and performance parameters.

```APIDOC
## Constructor: Part(name, ...)

### Description
Initializes a new musical part. This constructor accepts a wide range of parameters to configure the synthesizer engine, effects (reverb, delay, chorus, etc.), and performance characteristics like swing and humanization.

### Parameters
- **name** (str) - Required - The name of the part.
- **synth** (str) - Optional - The synthesizer engine to use (default: "sine").
- **envelope** (str) - Optional - The envelope type (default: "piano").
- **volume** (float) - Optional - The volume level (default: 0.5).
- **swing** (float) - Optional - Swing amount.
- **humanize** (float) - Optional - Humanization amount.
- **sidechain** (float) - Optional - Sidechain compression amount.
```

--------------------------------

### Start the live engine

Source: https://pytheory.org/_modules/pytheory/live.html

Initializes audio output and MIDI input, pre-renders wavetables, and blocks until interrupted. Requires python-rtmidi for MIDI functionality.

```python
    def start(self, port=None):
        """Start the engine - opens MIDI input and audio output.

        Args:
            port: MIDI port index or name. None = first available.

        Blocks until Ctrl-C or stop() is called.
        """
        if rtmidi is None:
            raise ImportError(
                "python-rtmidi is required for live MIDI. "
                "Install it with: pip install pytheory[live]"
            )

        if not self.channels:
            self.channel(1, instrument="electric_piano")

        # Pre-compute wavetables
        print("  Pre-rendering wavetables...")
        n_samples = SAMPLE_RATE * 3
        for _, channel in self.channels.items():
            if channel.is_drums:
                continue
            for midi_note in range(36, 97):
                channel._get_wave(midi_note, n_samples)
        print(f"  Cached {sum(len(c._cache) for c in self.channels.values())} wavetables.")
        print()

        # Open MIDI
        self._midi_in = rtmidi.MidiIn()
        ports = self._midi_in.get_ports()

        if not ports:
            print("  No MIDI input ports found. (Keyboard mode still works)")
            self._midi_in.delete()
            self._midi_in = None
            # Don't return — still start audio for keyboard mode

        port_name = "none"
        if self._midi_in and ports:
            if port is None:
                port = 0
            elif isinstance(port, str):
                matched = False
                for i, name in enumerate(ports):
                    if port.lower() in name.lower():
                        port = i
                        matched = True
                        break
                if not matched:
                    self._midi_in.delete()
                    self._midi_in = None
                    print(f"  MIDI port not found: {port!r}, continuing without MIDI")
                    port = None

            if self._midi_in and port is not None:
                try:
                    self._midi_in.open_port(port)
                    self._midi_in.ignore_types(sysex=True, timing=False, active_sense=True)
                    self._midi_in.set_callback(self._midi_callback)
                    port_name = ports[port]
                except Exception:
                    self._midi_in.delete()
                    self._midi_in = None
                    print("  Failed to open MIDI port, continuing without MIDI")

        print(f"  PyTheory Live Engine")
        print(f"  MIDI: {port_name}")
        print(f"  Buffer: {self.buffer_size} samples ({self.buffer_size/self.sample_rate*1000:.1f}ms)")
        print(f"  Channels:")
        for ch, channel in sorted(self.channels.items()):
            kind = "drums" if channel.is_drums else channel.synth_name
            print(f"    {ch:2d}: {kind} (vol={channel.volume})")
        if self._drum_pattern:
            sync = "Ableton Link" if self._link is not None else "MIDI clock"
            print(f"  Drums: {self._drum_pattern.name} (synced to {sync})")
        if self._link is not None:
            print(f"  Link: enabled — {self.link_peers()} peer(s), "
                  f"quantum {self._link_quantum:g}")
        print()
        print("  Playing... (Ctrl-C to stop)")
        print()

        self._stream = sd.OutputStream(
            samplerate=self.sample_rate,
            blocksize=self.buffer_size,
            channels=2,
            dtype='float32',
            callback=self._audio_callback,
        )

        try:
            self._stream.start()
            self._stop_event.clear()
            self._stop_event.wait()
        except KeyboardInterrupt:
            print("\n  Stopped.")
        finally:
            if self._stream:
                self._stream.stop()
                self._stream.close()
                self._stream = None
            if self._midi_in:
                self._midi_in.close_port()
                self._midi_in.delete()
                self._midi_in = None
```

--------------------------------

### Initialize a System instance

Source: https://pytheory.org/_modules/pytheory/systems.html

The System constructor defines the structure of a musical system, including tone names, degrees, and optional custom frequency ratios.

```python
class System:


    def __init__(self, *, tone_names, degrees, scales=None, c_index=None,
                 period=2.0, ratios=None):
        self.tone_names = tone_names

        self.degrees = degrees
        self._scales = scales

        # Period: the frequency ratio of one "octave" in this system.
        # 2.0 for standard octave-based systems.
        # 3.0 for Bohlen-Pierce (tritave).
        self.period = period

        # Custom frequency ratios: if set, overrides equal temperament.
        # A list of N floats (one per tone), each relative to the first
        # tone (1.0). For example, just intonation shruti ratios.
        self.ratios = ratios

        # c_index: the index of the "reference C" in the tone list.
        # For octave arithmetic — scientific pitch changes octave at C.
        # Default 3 for 12-TET western (A=0, A#=1, B=2, C=3).
        # For non-12-TET systems, this is the index of the tone nearest C,
        # or 0 if no C equivalent exists.
        if c_index is not None:
            self.c_index = c_index
        else:
            # Try to find C in the tone names, fall back to 0
            self.c_index = 0
            for i, names in enumerate(tone_names):
                if "C" in names:
                    self.c_index = i
                    break

        if scales is None:
            n = self.semitones
            if n in SCALES:
                self._scales = SCALES[n]
            else:
                # Generate chromatic scale for unknown sizes
                self._scales = {
                    "chromatic": (n, {}),
                }
```

--------------------------------

### Fretboard.keyboard

Source: https://pytheory.org/guide/fretboard.html

Initializes a keyboard controller configuration with a specified number of keys and starting note.

```APIDOC
## Fretboard.keyboard(keys, start_note)

### Description
Creates a keyboard instrument configuration.

### Parameters
- **keys** (int) - Optional - Number of keys (default 88).
- **start_note** (string) - Optional - The starting note of the keyboard (e.g., 'C2').
```

--------------------------------

### Initialize Oud Fretboard

Source: https://pytheory.org/_modules/pytheory/chords.html

Sets up the standard Arabic oud tuning (C4 G3 D3 A2 G2 C2).

```python
@classmethod
def oud(cls, high_to_low: bool = False) -> Fretboard:
    """Standard Arabic oud tuning (C4 G3 D3 A2 G2 C2).

    The oud is the ancestor of the European lute and the defining
    instrument of Arabic, Turkish, and Persian classical music.
    It is fretless, allowing the quarter-tone inflections
    essential to maqam performance. 6 courses (11 strings),
    typically tuned in fourths.
    """
    strings = ["C4", "G3", "D3", "A2", "G2", "C2"]
    return cls._from_canonical(strings, high_to_low)
```

--------------------------------

### Creating Tone Objects

Source: https://pytheory.org/guide/tones.html

Demonstrates instantiation of Tone objects using strings, explicit parameters, frequencies, and MIDI note numbers.

```python
>>> from pytheory import Tone

>>> c4 = Tone.from_string("C4")
>>> cs4 = Tone.from_string("C#4")
>>> db4 = Tone.from_string("Db4")

>>> d = Tone(name="D", octave=3)

>>> a4 = Tone.from_string("A4", system="western")

>>> Tone.from_frequency(440)
<Tone A4>
>>> Tone.from_frequency(261.63)
<Tone C4>

>>> Tone.from_midi(60)
<Tone C4>
>>> Tone.from_midi(69)
<Tone A4>

```

--------------------------------

### TonedScale.__init__(system, tonic)

Source: https://pytheory.org/_modules/pytheory/scales.html

Initializes a new TonedScale instance with a specified tone system and tonic note.

```APIDOC
## TonedScale.__init__(system, tonic)

### Description
Initializes a TonedScale with a tonic note and tone system.

### Parameters
- **system** (Union[str, System]) - Optional - A tone system name or System instance. Defaults to "western".
- **tonic** (Union[str, Tone]) - Required - The tonic note as a string (e.g., "C4") or Tone instance.
```

--------------------------------

### Get Parallel Modes

Source: https://pytheory.org/_sources/guide/scales.rst.txt

Retrieve all seven modes that share the same notes as the current scale.

```pycon
>>> for name, notes in c_major.parallel_modes().items():
...     print(f"{name}: {' '.join(notes)}")
C ionian: C D E F G A B C
D dorian: D E F G A B C D
E phrygian: E F G A B C D E
F lydian: F G A B C D E F
G mixolydian: G A B C D E F G
A aeolian: A B C D E F G A
B locrian: B C D E F G A B
```

--------------------------------

### Run Demo

Source: https://pytheory.org/_sources/guide/cli.rst.txt

Generate and play a random multi-part musical track.

```bash
$ pytheory demo
  ♫  Jazz Club
     Bb major | 108 bpm
     Bb → Gm → Cm → F
     jazz | triangle lead | fm pad | plate reverb
```

--------------------------------

### GET /ws

Source: https://pytheory.org/_modules/pytheory/tuner.html

Connect to the WebSocket endpoint to receive real-time pitch data updates.

```APIDOC
## GET /ws

### Description
Establishes a WebSocket connection to receive real-time pitch analysis data.

### Method
GET

### Endpoint
/ws

### Response
#### Success Response (200)
- **freq** (float) - Detected frequency in Hz
- **note** (string) - Note name
- **octave** (integer) - Octave number
- **cents** (float) - Signed deviation in cents (+ is sharp)
- **in_tune** (boolean) - True if within ±5 cents
- **chord** (string, optional) - Identified chord name if enabled

#### Response Example
{
  "freq": 440.0,
  "note": "A",
  "octave": 4,
  "cents": 0.0,
  "in_tune": true
}
```

--------------------------------

### Initialize Choir Synth

Source: https://pytheory.org/_sources/guide/synths.rst.txt

Demonstrates initializing the choir synth and adding notes with vowel lyrics.

```python
choir = score.part("choir", synth="choir_synth")
choir = score.part("choir", instrument="choir")  # ensemble=6 + cathedral reverb
choir.add("C4", Duration.WHOLE, lyric="ah")
```

--------------------------------

### Initializing Compound Time

Source: https://pytheory.org/_sources/guide/sequencing.rst.txt

Setup a score for compound time signatures like 12/8.

```python
from pytheory import Score, Duration, Key
```

--------------------------------

### Initialize Part class

Source: https://pytheory.org/_modules/pytheory/rhythm.html

Constructor for the Part class, defining synthesis, effects, and instrument parameters.

```python
    def __init__(self, name: str, *, synth: str = "sine",
                 envelope: str = "piano", volume: float = 0.5,
                 reverb: float = 0.0, reverb_decay: float = 1.0,
                 reverb_type: str = "algorithmic",
                 delay: float = 0.0, delay_time: float = 0.375,
                 delay_feedback: float = 0.4,
                 highpass: float = 0.0, highpass_q: float = 0.707,
                 lowpass: float = 0.0, lowpass_q: float = 0.707,
                 distortion: float = 0.0, distortion_drive: float = 3.0,
                 legato: bool = False, glide: float = 0.0,
                 chorus: float = 0.0, chorus_rate: float = 1.5,
                 chorus_depth: float = 0.003,
                 swing: Optional[float] = None,
                 humanize: float = 0.0,
                 sidechain: float = 0.0,
                 sidechain_release: float = 0.1,
                 detune: float = 0.0,
                 pan: float = 0.0,
                 spread: float = 0.0,
                 # ── New synth engine params ──
                 sub_osc: float = 0.0,
                 noise_mix: float = 0.0,
                 filter_attack: float = 0.01,
                 filter_decay: float = 0.3,
                 filter_sustain: float = 0.0,
                 filter_amount: float = 0.0,
                 vel_to_filter: float = 0.0,
                 saturation: float = 0.0,
                 tremolo_depth: float = 0.0,
                 tremolo_rate: float = 5.0,
                 phaser: float = 0.0,
                 phaser_rate: float = 0.5,
                 cabinet: float = 0.0,
                 cabinet_brightness: float = 0.5,
                 analog: float = 0.0,
                 ensemble: int = 1,
                 fm_ratio: float = 2.0,
                 fm_index: float = 3.0,
                 synth_kw: dict = None):
        self.name = name
        self.synth = synth
        self.envelope = envelope
        self.volume = volume
        self.swing = swing
        self.humanize = humanize
        self.sidechain = sidechain
        self.sidechain_release = sidechain_release
        self.reverb_mix = reverb
        self.reverb_decay = reverb_decay
        self.reverb_type = reverb_type
        self.delay_mix = delay
        self.delay_time = delay_time
        self.delay_feedback = delay_feedback
        self.highpass = highpass
        self.highpass_q = highpass_q
        self.lowpass = lowpass
        self.lowpass_q = lowpass_q
        self.distortion_mix = distortion
        self.distortion_drive = distortion_drive
        self.legato = legato
        self.glide = glide
        self.chorus_mix = chorus
        self.chorus_rate = chorus_rate
        self.chorus_depth = chorus_depth
        self.detune = detune
        self.pan = pan
        self.spread = spread
        # New synth engine params
        self.sub_osc = sub_osc
        self.noise_mix = noise_mix
        self.filter_attack = filter_attack
        self.filter_decay = filter_decay
        self.filter_sustain = filter_sustain
        self.filter_amount = filter_amount
        self.vel_to_filter = vel_to_filter
        self.saturation = saturation
        self.tremolo_depth = tremolo_depth
        self.tremolo_rate = tremolo_rate
        self.phaser_mix = phaser
        self.phaser_rate = phaser_rate
        self.cabinet = cabinet
        self.cabinet_brightness = cabinet_brightness
        self.analog = analog
        self.ensemble = ensemble
        self.fm_ratio = fm_ratio
        self.fm_index = fm_index
        self.synth_kw = synth_kw or {}
        self._system = "western"  # default, overridden by Score.part()
        self._fretboard = None    # set by Score.part(fretboard=...)
        self.notes: list[Note] = []
        self._drum_hits: list[_Hit] = []
        self._drum_pattern_beats: float = 0.0
        self._automation: list[tuple[float, dict]] = []  # (beat, {param: value})
```

--------------------------------

### Run Metronome with Chords

Source: https://pytheory.org/guide/cli.html

Starts a terminal metronome that cycles through specified chords or Roman numerals.

```bash
$ pytheory metronome 90 --chords C major I V vi IV
  Metronome: 90.0 BPM  (4/4)
  Cycling: C | G | Am | F
  Press Ctrl-C to stop.

  bar   1      90 BPM  C
  bar   2      90 BPM  G
  ...
```

--------------------------------

### Initialize and use the Key class

Source: https://pytheory.org/_modules/pytheory/scales.html

The Key class provides an entry point for scales and harmony, allowing access to notes, chords, and progressions.

```python
>>> key = Key("C", "major")
>>> key.scale.note_names
['C', 'D', 'E', 'F', 'G', 'A', 'B', 'C']
>>> key.chords
['C major', 'D minor', 'E minor', 'F major', ...]
>>> key.progression("I", "V", "vi", "IV")
[<Chord (C,E,G)>, <Chord (G,B,D)>, ...]
```

--------------------------------

### Fretboard.balalaika

Source: https://pytheory.org/api/chords.html

Initializes a Fretboard instance for a standard balalaika prima tuning.

```APIDOC
## Fretboard.balalaika(high_to_low: bool = False)

### Description
Returns a Fretboard instance configured for the standard balalaika prima tuning (A4 E4 E4).

### Parameters
- **high_to_low** (bool) - Optional - When True, the board reads high to low.
```

--------------------------------

### Run Command-Line Tuner

Source: https://pytheory.org/guide/listening.html

Initiates the live pitch tracking tuner in the terminal.

```bash
$ pytheory tune
  A4  ----------------------------●------ +12.3¢ ( 443.14 Hz)
```
Tokens:
Raw