{
  "markdown": "# raga\n\n[![PyPI version](https://img.shields.io/pypi/v/ragamala)](https://pypi.org/project/ragamala/)\n[![Python versions](https://img.shields.io/pypi/pyversions/ragamala)](https://pypi.org/project/ragamala/)\n[![License](https://img.shields.io/pypi/l/ragamala)](https://github.com/lukegrecki/raga/blob/main/LICENSE)\n[![CI](https://github.com/lukegrecki/raga/actions/workflows/ci.yml/badge.svg)](https://github.com/lukegrecki/raga/actions)\n[![Docs](https://img.shields.io/badge/docs-wiki-blue)](https://lukegrecki.com/raga/)\n\nA terminal reference tool for Hindustani classical music — look up ragas and talas, browse by time, mood, or feel, and get suggestions suited to the moment.\n\n## What is this?\n\nRagas and talas are the melodic and rhythmic foundations of Hindustani classical music. This tool helps you explore them: look up detailed information about any raga or tala, discover which ones suit a particular time of day or mood, and listen to audio previews. Whether you're a student learning Indian classical music, a listener discovering new ragas, or a musician planning your practice, this reference tool gives you quick access to the essential details.\n\n## Demo\n\nTry `raga suggest` to get ragas suited to the current time of day:\n\n```\n$ raga suggest\nSuggesting 3 raga(s) for afternoon\n\n╭─────────────────────── Madhuvanti ─────────────────────╮\n│  Thaat           Todi                                  │\n│  Time            Afternoon                             │\n│  Mood            sweet, yearning, romantic             │\n│  Arohana         Sa Re Ga Ma♯ Pa Ni SA                 │\n│  Avarohana       SA Ni Dha Pa Ma♯ Ga Re Sa             │\n│                                                        │\n│  A relatively modern raga... [description continues]  │\n╰────────────────────────────────────────────────────────╯\n```\n\nOr look up a specific raga with colored notation and detailed analysis:\n\n```\n$ raga lookup yaman\n\n╭─────────────────── Yaman ─────────────────────────────╮\n│  Thaat           Kalyan                                │\n│  Time            Evening                               │\n│  Vadi / Samvadi  Ga / Ni                               │\n│  Mood            serene, romantic, devotional          │\n│  Arohana         Sa Re Ga Ma♯ Pa Dha Ni SA             │\n│  Avarohana       SA Ni Dha Pa Ma♯ Ga Re Sa             │\n│                                                        │\n│  One of the most foundational and widely taught       │\n│  ragas... [description continues]                     │\n╰────────────────────────────────────────────────────────╯\n```\n\n## Installation\n\n```bash\npip install ragamala\n```\n\nRequires Python 3.11 or later.\n\n## Quick Start\n\n```bash\nraga suggest                  # suggest ragas for the current time\nraga lookup yaman             # detailed view of one raga\nraga list --mood devotional   # filter by mood\n\ntala lookup teentaal          # look up a tala by name\ntala list --beats 16          # filter by beat count\n```\n\n## Optional: Audio Playback\n\nThe `raga play` command requires FluidSynth and a SoundFont file. The `lookup`, `list`, and `suggest` commands work without audio.\n\n### Install FluidSynth\n\n```bash\n# macOS\nbrew install fluid-synth\n\n# Debian/Ubuntu\napt install fluidsynth\n\n# Windows\n# Download from https://github.com/FluidSynth/fluidsynth/releases\n```\n\n### Install the audio extra\n\n```bash\npip install 'ragamala[audio]'\n```\n\n### Get a SoundFont\n\nDownload a free SoundFont file (e.g., `FluidR3_GM.sf2`) from the [FluidSynth project](https://github.com/FluidSynth/fluidsynth/wiki/SoundFont) or [MuseScore](https://musescore.org/en/handbook/3/soundfonts-and-sfz-files). Then pass it to `raga play`:\n\n```bash\nraga play yaman --soundfont /path/to/FluidR3_GM.sf2\n```\n\nOr set the `RAGA_SOUNDFONT` environment variable once:\n\n```bash\nexport RAGA_SOUNDFONT=/path/to/FluidR3_GM.sf2\nraga play yaman   # uses the env var\n```\n\n## Commands\n\n### raga\n\n```bash\nraga lookup <name>              # look up a raga by name (fuzzy match)\nraga list                       # list all ragas\nraga list --thaat Kalyan        # filter by thaat\nraga list --time evening        # filter by time of day\nraga list --mood devotional\nraga list --season spring\nraga list --plain               # plain text output (no color, pipe-friendly)\nraga list --output ragas.txt    # write plain text to a file\n\nraga suggest                    # suggest ragas for the current time of day\nraga suggest --time morning     # suggest for a specific time\nraga suggest --mood romantic    # suggest by mood\nraga suggest --time dusk --mood solemn --count 5\n\nraga play <name>                # play arohana+avarohana via FluidSynth\nraga play <name> --sa D4        # set Sa reference pitch (default: C4)\nraga play <name> --tempo 60     # set tempo in BPM (default: 80)\nraga play <name> --soundfont /path/to/FluidR3_GM.sf2\n```\n\n### tala\n\n```bash\ntala lookup <name>              # look up a tala by name (fuzzy match)\ntala list                       # list all talas\ntala list --beats 16            # filter by beat count\ntala list --feel stately        # filter by feel\ntala list --tempo vilambit      # filter by tempo\ntala list --plain               # plain text output (no color, pipe-friendly)\ntala list --output talas.txt    # write plain text to a file\n\ntala suggest                    # suggest talas from the full collection\ntala suggest --beats 16         # suggest talas with a specific beat count\ntala suggest --feel lively      # suggest by feel\ntala suggest --tempo drut --count 2\n```\n\n### Shell completions\n\nBoth `raga` and `tala` support tab completion for all options and their values (raga names, thaats, times, moods, seasons, feels, tempos, beat counts).\n\n```bash\nraga --install-completion       # install completion for your current shell\ntala --install-completion\n\nraga --show-completion          # print the completion script (for manual setup)\ntala --show-completion\n```\n\nSupported shells: bash, zsh, fish, PowerShell.\n\n## Reference\n\n### Raga time values\n\n`dawn` · `morning` · `afternoon` · `evening` · `dusk` · `night` · `late night` · `midnight` · `any`\n\n`raga suggest` defaults to the current time of day when called with no arguments.\n\n### Swara notation\n\nSwaras are displayed with color: komal (flat) notes in yellow, tivra (sharp) Ma in magenta. Upper-octave SA is bold.\n\n### Tala theka notation\n\nBols prefixed with `~` are khali (unaccented) beats, rendered dim and italic.\n\n## Data\n\nRagas and talas are stored as JSON in `src/raga/data/`. To add entries, edit `ragas.json` or `talas.json` directly — no code changes needed.\n\n## Development\n\nTo contribute, first install in development mode:\n\n```bash\npip install -e \".[dev]\"\n```\n\nThen run tests:\n\n```bash\npython -m pytest tests/ -v\n```\n",
  "bytes": 6725,
  "sha": "9dc657b0a0592a70d46e4e1a19a8672d1dbdee25fbb315f935b82211b650be09",
  "repo_slug": "lukegrecki/raga",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_lukegrecki_raga_openwiki_index_md_692f8caf/readme"
}