---
warning: DO NOT CHANGE THIS MANUALLY, THIS IS GENERATED BY https://github.com/duckdb/community-extensions repository, check README there
title: midi
excerpt: |
  DuckDB Community Extensions
  Read, analyze, generate, and play MIDI files with SQL. Provides table functions for parsing Standard MIDI Files, scalar functions for note/frequency conversion, and macOS playback via AudioToolbox.

extension:
  name: midi
  description: Read, analyze, generate, and play MIDI files with SQL. Provides table functions for parsing Standard MIDI Files, scalar functions for note/frequency conversion, and macOS playback via AudioToolbox.
  version: 0.1.0
  language: C++
  build: cmake
  license: MIT
  requires_toolchains: ""
  maintainers:
    - nkwork9999

repo:
  github: nkwork9999/duckdb-midi
  ref: bd85cbe38388923ea1a9ebc597d81676e9287582

docs:
  hello_world: |
    -- Load the extension
    LOAD midi;

    -- Generate a test MIDI file
    SELECT midi_gen('/tmp/test.mid', 'scale');

    -- Read all events
    SELECT * FROM read_midi('/tmp/test.mid') LIMIT 10;

    -- Analyze notes with pairing
    SELECT note_name, count(*) as freq, round(avg(duration_sec), 2) as avg_dur
    FROM midi_notes('/tmp/test.mid')
    GROUP BY note_name ORDER BY freq DESC;

    -- Play (macOS only)
    SELECT midi_play('/tmp/test.mid');

  extended_description: |
    duckdb-midi brings MIDI file support to DuckDB. Parse, analyze, generate, and play
    Standard MIDI Files entirely from SQL.

    **Table Functions**:
    - `read_midi(path)` - All MIDI events as a table (note_on, note_off, control_change, meta, etc.)
    - `midi_notes(path)` - Note-on/off pairs with duration, velocity, and note name
    - `midi_meta(path)` - Meta events (tempo, time signature, key signature, track names)

    **Scalar Functions**:
    - `midi_note_name(60)` → `'C4'`
    - `midi_note_number('C4')` → `60`
    - `midi_note_freq(69)` → `440.0`
    - `midi_bpm_to_uspqn(120.0)` → `500000`
    - `midi_uspqn_to_bpm(500000)` → `120.0`

    **Write / Generate**:
    - `midi_write(path, notes[], durations[], velocities[], bpm)` - Create MIDI from arrays
    - `midi_gen(path, preset)` - Generate test MIDI (scale, chord, arpeggio, drum, chromatic)

    **Playback (macOS)**:
    - `midi_play(path)` - Play MIDI file (blocks until finished)
    - `midi_stop()` - Stop playback

    Uses [craigsapp/midifile](https://github.com/craigsapp/midifile) for SMF parsing/writing
    and macOS AudioToolbox for playback.

extension_star_count: 0
extension_star_count_pretty: 0
extension_download_count: 537
extension_download_count_pretty: 537
image: '/images/community_extensions/social_preview/preview_community_extension_midi.png'
layout: community_extension_doc
---
### Compatibility Matrix

This table covers all DuckDB releases that have not reached [end-of-life](https://duckdb.org/release_calendar), including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.

<div class="extension_compatibility_table"></div>

| Platform | 1.4.4 | 1.4.5 | 1.5.5 | 1.5.6 | 2.0.0 |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Linux AMD64 | ❌ | ❌ | ❌ | ❌ | ✅ |
| Linux ARM64 | ❌ | ❌ | ❌ | ❌ | ✅ |
| macOS AMD64 | ❌ | ❌ | ❌ | ❌ | ✅ |
| macOS ARM64 | ❌ | ❌ | ❌ | ❌ | ✅ |
| Windows AMD64 | ❌ | ❌ | ❌ | ❌ | ✅ |
| Windows ARM64 | ❌ | ❌ | ❌ | ❌ | ❌ |
| WebAssembly | ❌ | ❌ | ❌ | ❌ | ✅ |

### Installing and Loading
```sql
INSTALL {{ page.extension.name }} FROM community;
LOAD {{ page.extension.name }};
```

{% if page.docs.hello_world %}
### Example
```sql
{{ page.docs.hello_world }}```
{% endif %}

{% if page.docs.extended_description %}
### About {{ page.extension.name }}
{{ page.docs.extended_description }}
{% endif %}
### Added Functions

<div class="extension_functions_table"></div>

|   function_name   | function_type | description | comment | examples |
|-------------------|---------------|-------------|---------|----------|
| midi_bpm_to_uspqn | scalar        | NULL        | NULL    |          |
| midi_gen          | scalar        | NULL        | NULL    |          |
| midi_meta         | table         | NULL        | NULL    |          |
| midi_note_freq    | scalar        | NULL        | NULL    |          |
| midi_note_name    | scalar        | NULL        | NULL    |          |
| midi_note_number  | scalar        | NULL        | NULL    |          |
| midi_notes        | table         | NULL        | NULL    |          |
| midi_play         | scalar        | NULL        | NULL    |          |
| midi_stop         | scalar        | NULL        | NULL    |          |
| midi_uspqn_to_bpm | scalar        | NULL        | NULL    |          |
| midi_write        | scalar        | NULL        | NULL    |          |
| read_midi         | table         | NULL        | NULL    |          |

### Overloaded Functions

<div class="extension_functions_table"></div>

This extension does not add any function overloads.

### Added Types

<div class="extension_types_table"></div>

This extension does not add any types.

### Added Settings

<div class="extension_settings_table"></div>

|      name      |                       description                       | input_type | scope  | aliases | typed_value |
|----------------|---------------------------------------------------------|------------|--------|---------|-------------|
| temp_directory | Set the directory to which temporary files are written. | VARCHAR    | GLOBAL | []      | post.db.tmp |