← MidiPilot overview

MidiPilot Settings and Providers

Everything you set up once and then stop thinking about: the provider and model connection, the prompts MidiPilot sends with each request, the settings it remembers per file, and the counters and logs that show what a request actually cost.

AI Settings

Configure your AI connection from Settings → MidiPilot AI. Select a provider, enter your API key, choose a model, and customize behavior.

Model Refresh & Favorites

MidiEditor AI can fetch provider model lists directly instead of relying on a fixed dropdown. The refresh button is available both in Settings → MidiPilot AI and in the MidiPilot footer, so you can update models without leaving the chat panel. Refreshed models are cached for seven days and used for context-window estimates.

When the footer refresh completes, MidiPilot reports the result in the chat/status area so you know whether the cache was updated or the provider rejected the request.

Model update feedback after a successful refresh

If a model fails live streaming but still works without streaming, MidiPilot retries automatically and marks that model with a warning icon for the current app session. The mark is scoped per mode - Simple Mode (no tools) and Agent Mode (with tools) are tracked independently, because some models support live streaming in only one of the two paths. The dropdown shows which mode is blocked: ⚠ <model> (Simple), (Agent), or (Simple+Agent). Use Force Streaming for This Model to clear the temporary mark after switching providers, updating the model, or testing a fixed endpoint.

Capability-aware error handling - if the active provider returns HTTP 404 with “No endpoints found that support tool use” (or any equivalent “tools not supported” error), MidiPilot stops retrying immediately, posts a clear “Model does not support tool calling - pick a different model in Settings → AI, or switch to Simple mode for this request” bubble, and remembers the flag per provider:model for the rest of the session. Picking a different model re-enables Agent Mode automatically.

Supported Providers

Local AI with Ollama (free, private, no API key)

Ollama runs an open-weight language model entirely on your own machine - no API key, no cloud account, no per-token cost, and nothing leaves your PC. Setup is a one-time step, comparable to getting a cloud API key:

1. Install Ollama. Download it from ollama.com and run the installer. After installation the Ollama server runs in the background and listens on http://localhost:11434.
2. Pull a model. From a terminal, run e.g. ollama pull llama3.1:8b. Pick a model that advertises the tools capability if you want to use Agent Mode (the agent drives MidiPilot's tools to compose/edit; a chat-only model can still answer in Simple Mode). Smaller models download faster and respond quicker; large models need a capable GPU and lots of disk.
3. Configure MidiPilot. In Settings → MidiPilot AI, set Provider to Ollama (local). The Base URL auto-fills to http://localhost:11434/v1 and the API key field can stay empty. Click the 🔄 Refresh button to list your installed models (with size badges), pick one, and click Test Connection.

If Test Connection reports the server can't be reached, make sure Ollama is actually running (launch the Ollama app, or run ollama serve in a terminal), then try again.

Two things worth knowing about local models

• They are given more time. A local model runs on your own GPU and a mid-sized one routinely needs minutes for a single turn - and without live streaming a local server sends nothing at all until the whole answer is finished, so from the outside the request looks idle the entire time. MidiPilot therefore allows a local provider a considerably longer request window than a cloud provider, and a slow answer is not treated as a dead connection. If a request does time out, the message says so and suggests the answer may simply need longer.
• If it writes bends instead of notes, take the option away. Small models sometimes answer “write me a melody” with a lone pitch bend, because a bend is the cheapest event to produce. Give that model a prompt profile with Hide pitch-bend events from this model ticked and the shortcut disappears - it has to write real notes.

Hugging Face via the Custom provider

The Hugging Face inference router speaks the same protocol as OpenAI, so it plugs straight into the Custom provider - no separate integration needed. This gives MidiPilot access to open-weight model families such as Llama, Qwen and DeepSeek, hosted by Hugging Face's inference partners.

1. Create an access token. On huggingface.co/settings/tokens, create a token with the Inference permission (the "Make calls to Inference Providers" right is what the router checks).
2. Configure MidiPilot. In Settings → MidiPilot AI, set Provider to Custom, the Base URL to https://router.huggingface.co/v1, and paste the token as the API key.
3. Refresh the model list and pick a model. Streaming works like with any other OpenAI-compatible endpoint, and models that support tool calling can be used in Agent mode.

Prompt Profiles (Per-Model System Prompts)

Open Settings → MidiPilot AI → Prompt Profiles…, or Prompt Profiles… from the ⚙ gear menu in the MidiPilot footer, to manage profiles. A profile binds a custom system prompt to one or more model patterns and decides whether the profile replaces or appends to the default mode prompt.

Hide pitch-bend events from this model (schema-level). Of all the things MidiPilot can write into a track, a pitch bend is the cheapest to describe - a note needs a pitch, a velocity, a length and a position, a bend needs almost nothing. A model that is unsure of itself will therefore sometimes answer a “write me a melody” request with a single pitch bend and nothing else, no matter how clearly the prompt asks for notes. Tick this box and the bend simply stops being an option: it is taken out of the tool description the model receives, so it has to write real notes.

• Per profile, per model. The switch belongs to the profile, so it only affects the provider:model patterns that profile is bound to. Every other model keeps the full set of event types.
• Agent mode only. That is where a tool schema exists; Simple mode sends a single request without one, so the setting has nothing to act on there.
• MidiPilot only. An external client connected to the MCP server always receives the complete schema, bends included - the switch is a setting for the built-in agent, not a property of the file or of the tools themselves.
• Turn it off when you want bends. If you want that model to write real pitch bends or vibrato for you, leave the box unchecked. This is a workaround for a model that substitutes bends for notes, not a rule about how music should be written.

A local model is the most common reason to reach for it - see Local AI with Ollama.

The per-profile switch: tick it for a model that writes placeholder bends and leave every other model untouched.

MidiPilot ships with one built-in profile: GPT-5.5 Decisive, bound to openai:gpt-5.5* and openrouter:openai/gpt-5.5*. It nudges the model to commit to a tool call instead of asking clarifying questions, which is a known weak spot of that family. You can edit, duplicate, or disable it like any other profile.

Prompt Profiles dialog with the built-in GPT-5.5 Decisive profile bound to openai:gpt-5.5* and openrouter:openai/gpt-5.5*

Custom System Prompts

Click Edit System Prompts… in settings to open the built-in editor. Each mode (Simple, Agent, FFXIV, FFXIV Compact) has its own tab with fully customizable instructions.

Built-in System Prompt Editor with tab-based mode selection

• Load Default - Reset the current tab to the built-in default prompt
• Export to JSON - Save all prompts to a file for backup or sharing
• Import from JSON - Load prompts from a previously exported file
• Reset All to Defaults - Restore all modes to factory defaults

Prompts are saved as system_prompts.json in the application directory. If no custom file exists, MidiPilot uses the hardcoded defaults.

Looking for per-model overrides? The newer Prompt Profiles dialog lets you attach a dedicated system prompt to one or more provider:model combinations - great for guiding a single “quirky” model without touching the global mode prompts.

Per-File AI Presets

Different MIDI files may need different AI settings. A 16-track orchestral arrangement needs different guidance than a 3-track FFXIV bard song. Per-file presets let you save and auto-load settings for each file.

What’s Saved

• Provider - OpenAI, OpenRouter, Gemini, Ollama (local), or Custom
• Model - e.g., gpt-5.4, gemini-2.5-flash
• Mode - Simple or Agent
• FFXIV mode - On or off
• Reasoning effort - None / Low / Medium / High / Extra High
• Custom instructions - Free-text notes appended to the system prompt (e.g., “This is a jazz arrangement, keep swing feel”)

How to Use

1. Click the ⚙ gear button in the MidiPilot footer
2. Select “Save AI preset for this file”
3. The current settings are saved as a .midipilot.json sidecar file next to your MIDI file
4. Next time you open that MIDI file, the preset is auto-loaded

Sidecar File

Presets are stored as <filename>.midipilot.json next to the MIDI file. For example:

Sweet Child O Mine.mid
Sweet Child O Mine.mid.midipilot.json   ← preset

The preset file is a simple JSON object. All fields are optional - any field not present falls back to the global default.

Auto-Save

MidiEditor AI automatically saves a backup copy of your work at regular intervals, so you never lose progress to a crash or accidental close. Your original file is never overwritten - the backup is stored as a separate .autosave sidecar file alongside your MIDI file.

How It Works

• Debounce timer - after each edit, a countdown resets. The backup is only written once you pause editing for the configured interval (default: 120 seconds).
• Named files - saved as YourSong.mid.autosave next to the original file.
• Untitled documents - saved to AppData/MidiEditor AI/autosave/untitled.autosave.mid.
• Cleanup - the .autosave backup is automatically deleted when you save normally or exit cleanly.
• Protocol entry - each auto-save appears as an “Auto-saved” marker in the undo history panel.

Crash Recovery

• When opening a file, if a newer .autosave backup exists, MidiEditor AI offers to recover it.
• On startup, orphaned untitled backups from previous crashes are detected and a recovery dialog is shown.
• Recovered files open as unsaved - use Save As to give them a permanent name.

Settings

Auto-save options are in Settings → System & Performance:

Auto-Save settings with enable toggle and interval configuration

Token Tracking & Context Window

MidiPilot tracks token usage per API call and per session, with automatic normalization across providers (OpenAI, Anthropic, Gemini). The token counter is displayed at the bottom of the chat panel:

<last call> | <session total>🔥 / <context window> [<limit>✂]

• Last call - Prompt + completion tokens from the most recent API call
• Session total - Cumulative tokens since the chat was opened (🔥 fire icon)
• Context window - The model’s known context limit (e.g., 128k for GPT-4o, 1M for GPT-5). Turns yellow when usage exceeds 80%
• Limit - Only shown when a max token limit is enabled (✂ scissors icon)

Context Window Management

When conversations grow long, MidiPilot automatically manages context to prevent exceeding the model’s limit:

• Sliding window - When estimated token usage exceeds 70% of the context window, older messages are dropped while keeping the system prompt, first 2 messages (task context), and most recent messages
• Truncation marker - A “[Context truncated]” message is inserted where older messages were removed
• Visual warning - The token label turns yellow when approaching 80% of the context window

Multi-Provider Token Normalization

Different providers report token usage in different formats. MidiPilot normalizes all of them:

• OpenAI Chat Completions - prompt_tokens / completion_tokens (native format)
• OpenAI Responses API - input_tokens / output_tokens → normalized
• Anthropic - input_tokens / output_tokens → normalized
• Google Gemini - usageMetadata.promptTokenCount / candidatesTokenCount → normalized
• Estimation fallback - When a provider returns no usage data, MidiPilot estimates ~4 characters per token

API Log

MidiPilot writes every API request and response to a log file for debugging and transparency. The log is saved as midipilot_api.log in the same directory as the MidiEditor AI executable.

If the AI produces unexpected results, open the log to inspect the raw JSON sent to and received from the provider. This is especially useful for debugging tool-call sequences in Agent mode.

See also

• MidiPilot - Your AI Copilot - the overview: key features, getting started, the chat panel, and the mode comparison table.
• MidiPilot Modes and Conversations - what the mode, streaming, and reasoning settings on this page actually switch between.
• MidiPilot in FFXIV Bard Mode - what the FFXIV Mode setting turns on.
• MidiPilot AI Tools Reference - every tool Agent mode can call, and the MCP server that exposes the same set.