Skip to content

getting_started.md

Latest commit

 

History

History
89 lines (68 loc) · 3.86 KB

getting_started.md

File metadata and controls

89 lines (68 loc) · 3.86 KB
Raw

Getting Started

STALGIA Logo

This guide explains how to install dependencies and run STALGIA on your local machine.

Prerequisites

  1. Python 3.10+: Ensure Python is installed and accessible in your system PATH.
  2. FluidSynth (System Audio Library): REQUIRED for MIDI-to-Audio background rendering. You must install the system-level C library, not just the python package:
    • macOS: brew install fluidsynth (Note for Apple Silicon/M1+ users: Homebrew installs to /opt/homebrew/lib. If you run scripts outside of app.py, you may need to add export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib to your ~/.zshrc so Python can find it.)
    • Linux: sudo apt install fluidsynth
    • Windows: Download the compiled release and add the bin directory to your System PATH.
  3. A model provider: the default is Google Gemini (Google AI Studio API key). OpenAI, Anthropic, OpenAI-compatible cloud endpoints, and local servers (e.g. Ollama) are also supported; see LLM_config.md.

Installation

  1. Clone the repository.
  2. Create a virtual environment: 
    python -m venv .venv
  3. Activate the virtual environment:
    • Windows (PowerShell):
    .\.venv\Scripts\Activate.ps1
    • macOS/Linux:
    source .venv/bin/activate
  4. Install Requirements: 
    pip install -r requirements.txt
    Note: requirements.txt installs musicpy[daw], google-genai, openai, anthropic, flask, flask-cors, flasgger, pretty_midi, pytest, and audioop-lts (for Python 3.13+ compatibility).

Configuration

For the default Gemini provider, set the GEMINI_API_KEY environment variable before starting the app or CLI. To use another provider, set LLM_PROVIDER and the related variables described in LLM_config.md.

  • Windows: 
    $env:GEMINI_API_KEY="YOUR_API_KEY_HERE"
  • macOS/Linux: 
    export GEMINI_API_KEY="YOUR_API_KEY_HERE"

Soundfont Note: The audio export mechanism relies on an .sf2 soundfont provided by pretty_midi. The system automatically resolves its dynamic path (e.g. pretty_midi/TimGM6mb.sf2) directly from the installed package.

Running the Application

Start the Flask development server from the root directory:

python app.py

Wait a few seconds for the application bundle to load. Open a web browser and navigate directly to:

  • Main App Interface: http://127.0.0.1:8080/ (Served dynamically by the Flask root route, no need for separate file hosting!)
  • Interactive API Docs (Swagger): http://127.0.0.1:8080/apidocs/

Command-Line Interface

cli.py drives STALGIA without the web UI (run it with the virtual environment active):

python cli.py generate "an upbeat lo-fi piano loop" -o song.mid --code-out song.py
python cli.py generate @prompt.txt --config '{"genre": "ambient"}' --json
python cli.py render song.py -o song.mid          # musicpy code -> MIDI (use - for stdin)
python cli.py revise "original prompt" song.py "make it slower" -o song2.mid
python cli.py audio song.mid -o song.mp3          # requires FluidSynth
python cli.py serve --port 8080                   # run the web UI/API

generate, render, and revise accept -o (MIDI path, default ./output.mid), --code-out (write code to a file instead of printing it), and --json (print the full result). Errors are written to stderr with a non-zero exit code. Provider and model selection use the same environment configuration as the web app (see LLM_config.md). Verified prepackaged example prompts render without provider credentials on non-Gemini providers.

Running Tests

pytest