## AgsMidiFile

AgsMidiFile — the MIDI file

## Stability Level

Stable, unless otherwise indicated

## Functions

#define | AGS_MIDI_FILE_GET_OBJ_MUTEX()
#define | AGS_MIDI_FILE_TRACK()
GQuark | ags_midi_file_error_quark ()
gboolean | ags_midi_file_open ()
gboolean | ags_midi_file_open_from_data ()
gboolean | ags_midi_file_rw_open ()
void | ags_midi_file_close ()
unsigned char * | ags_midi_file_read ()
void | ags_midi_file_write ()
void | ags_midi_file_seek ()
void | ags_midi_file_flush ()
unsigned char | ags_midi_file_read_byte ()
gint16 | ags_midi_file_read_gint16 ()
gint32 | ags_midi_file_read_gint24 ()
gint32 | ags_midi_file_read_gint32 ()
long | ags_midi_file_read_varlength ()
unsigned char * | ags_midi_file_read_text ()
void | ags_midi_file_write_byte ()
void | ags_midi_file_write_gint16 ()
void | ags_midi_file_write_gint24 ()
void | ags_midi_file_write_gint32 ()
void | ags_midi_file_write_varlength ()
void | ags_midi_file_write_text ()
unsigned char * | ags_midi_file_read_header ()
void | ags_midi_file_write_header ()
unsigned char * | ags_midi_file_read_track_data ()
void | ags_midi_file_write_track_data ()
void | ags_midi_file_read_notation ()
void | ags_mid_file_read_midi ()
AgsMidiFile * | ags_midi_file_new ()

## Properties

char * | filename | Read / Write

## Types and Values

#define | AGS_MIDI_FILE_MAX_TEXT_LENGTH
#define | AGS_MIDI_FILE_MTHD
#define | AGS_MIDI_FILE_MTRK
#define | AGS_MIDI_FILE_DEFAULT_OFFSET
#define | AGS_MIDI_FILE_DEFAULT_FORMAT
#define | AGS_MIDI_FILE_DEFAULT_BEATS
#define | AGS_MIDI_FILE_DEFAULT_FPS
#define | AGS_MIDI_FILE_DEFAULT_TICKS
enum | AgsMidiFileStatus
enum | AgsMidiFileFlags
#define | AGS_MIDI_FILE_ERROR
enum | AgsMidiFileError
struct | AgsMidiFileTrack

## Object Hierarchy

        GObject
        ╰── AgsMidiFile

## Includes

    #include <ags/audio/midi/ags_midi_file.h>

## Description

AgsMidiFile reads or writes your midi files.

## Functions

### AGS_MIDI_FILE_GET_OBJ_MUTEX()

    #define AGS_MIDI_FILE_GET_OBJ_MUTEX(obj) (&(((AgsMidiFile *) obj)->obj_mutex))

### AGS_MIDI_FILE_TRACK()

    #define AGS_MIDI_FILE_TRACK(ptr) ((AgsMidiFileTrack *)(ptr))

### ags_midi_file_error_quark ()

    GQuark
    ags_midi_file_error_quark ();

### ags_midi_file_open ()

    gboolean
    ags_midi_file_open (AgsMidiFile *midi_file,
                        gchar *filename);

Opens a MIDI file read-only.

#### Parameters

midi_file | the AgsMidiFile |
filename | the filename |

#### Returns

`TRUE` on success, otherwise `FALSE`

Since: 3.0.0

### ags_midi_file_open_from_data ()

    gboolean
    ags_midi_file_open_from_data (AgsMidiFile *midi_file,
                                  unsigned char *data,
                                  guint buffer_length);

Opens a virtual MIDI file residing in `data` 's array.

#### Parameters

midi_file | the AgsMidiFile |
data | the buffer to set |
buffer_length | the length of the buffer |

#### Returns

`TRUE` on success, otherwise `FALSE`

Since: 3.0.0

### ags_midi_file_rw_open ()

    gboolean
    ags_midi_file_rw_open (AgsMidiFile *midi_file,
                           gchar *filename,
                           gboolean create);

Opens a MIDI file with read-write permission.

#### Parameters

midi_file | the AgsMidiFile |
filename | the filename |
create | `TRUE` create file if not exists, else if `FALSE` return |

#### Returns

`TRUE` on success, otherwise `FALSE`

Since: 3.0.0

### ags_midi_file_close ()

    void
    ags_midi_file_close (AgsMidiFile *midi_file);

Closes the file stream.

#### Parameters

midi_file | the AgsMidiFile |

Since: 3.0.0

### ags_midi_file_read ()

    unsigned char *
    ags_midi_file_read (AgsMidiFile *midi_file);

Reads all bytes of the file's stream and stores them in the internal buffer.

#### Parameters

midi_file | the AgsMidiFile |

#### Returns

the data array just read

Since: 3.0.0

### ags_midi_file_write ()

    void
    ags_midi_file_write (AgsMidiFile *midi_file,
                         unsigned char *data,
                         guint buffer_length);

Writes `data` to the file stream and to internal buffer, reallocates it if necessary.

#### Parameters

midi_file | the AgsMidiFile |
data | the data array to write |
buffer_length | n-bytes to write |

Since: 3.0.0

### ags_midi_file_seek ()

    void
    ags_midi_file_seek (AgsMidiFile *midi_file,
                        guint position,
                        gint whence);

Seeks the file stream's offset.

#### Parameters

midi_file | the AgsMidiFile |
position | the offset |
whence | SEEK_SET, SEEK_END, or SEEK_CUR |

Since: 3.0.0

### ags_midi_file_flush ()

    void
    ags_midi_file_flush (AgsMidiFile *midi_file);

Flushes file stream's data buffer to disc.

#### Parameters

midi_file | the AgsMidiFile |

Since: 3.0.0

### ags_midi_file_read_byte ()

    unsigned char
    ags_midi_file_read_byte (AgsMidiFile *midi_file,
                             GError **error);

Reads a unsigned char quantity.

#### Parameters

midi_file | the AgsMidiFile |
error | the GError pointer return location |

#### Returns

the current value at file's iteration pointer

Since: 3.0.0

### ags_midi_file_read_gint16 ()

    gint16
    ags_midi_file_read_gint16 (AgsMidiFile *midi_file,
                               GError **error);

Reads a gint16 quantity.

#### Parameters

midi_file | the AgsMidiFile |
error | the GError pointer return location |

#### Returns

the current value at file's iteration pointer

Since: 3.0.0

### ags_midi_file_read_gint24 ()

    gint32
    ags_midi_file_read_gint24 (AgsMidiFile *midi_file,
                               GError **error);

Reads a 24-bit quantity.

#### Parameters

midi_file | the AgsMidiFile |
error | the GError pointer return location |

#### Returns

the current value at file's iteration pointer

Since: 3.0.0

### ags_midi_file_read_gint32 ()

    gint32
    ags_midi_file_read_gint32 (AgsMidiFile *midi_file,
                               GError **error);

Reads a gint32 quantity.

#### Parameters

midi_file | the AgsMidiFile |
error | the GError pointer return location |

#### Returns

the current value at file's iteration pointer

Since: 3.0.0

### ags_midi_file_read_varlength ()

    long
    ags_midi_file_read_varlength (AgsMidiFile *midi_file,
                                  GError **error);

Reads a variable length quantity.

#### Parameters

midi_file | the AgsMidiFile |
error | the GError pointer return location |

#### Returns

the current value at file's iteration pointer

Since: 3.0.0

### ags_midi_file_read_text ()

    unsigned char *
    ags_midi_file_read_text (AgsMidiFile *midi_file,
                             gint length,
                             GError **error);

Reads a string.

#### Parameters

midi_file | the AgsMidiFile |
length | the number of bytes to be read, or as long valid string for -1 |
error | the GError pointer return location |

#### Returns

the string at file's iteration pointer

Since: 3.0.0

### ags_midi_file_write_byte ()

    void
    ags_midi_file_write_byte (AgsMidiFile *midi_file,
                              unsigned char val);

Writes a unsigned char quantity to internal buffer.

#### Parameters

midi_file | the AgsMidiFile |
val | the value to write |

Since: 3.0.0

### ags_midi_file_write_gint16 ()

    void
    ags_midi_file_write_gint16 (AgsMidiFile *midi_file,
                                gint16 val);

Writes a gint16 quantity to internal buffer.

#### Parameters

midi_file | the AgsMidiFile |
val | the value to write |

Since: 3.0.0

### ags_midi_file_write_gint24 ()

    void
    ags_midi_file_write_gint24 (AgsMidiFile *midi_file,
                                gint32 val);

Writes a 24-bit quantity to internal buffer.

#### Parameters

midi_file | the AgsMidiFile |
val | the value to write |

Since: 3.0.0

### ags_midi_file_write_gint32 ()

    void
    ags_midi_file_write_gint32 (AgsMidiFile *midi_file,
                                gint32 val);

Writes a gint32 quantity to internal buffer.

#### Parameters

midi_file | the AgsMidiFile |
val | the value to write |

Since: 3.0.0

### ags_midi_file_write_varlength ()

    void
    ags_midi_file_write_varlength (AgsMidiFile *midi_file,
                                   long val Param2);

### ags_midi_file_write_text ()

    void
    ags_midi_file_write_text (AgsMidiFile *midi_file,
                              gchar *text,
                              guint length);

Writes a string to internal buffer up to length bytes.

#### Parameters

midi_file | the AgsMidiFile |
text | the text |
length | the string's length |

Since: 3.0.0

### ags_midi_file_read_header ()

    unsigned char *
    ags_midi_file_read_header (AgsMidiFile *midi_file,
                               guint *buffer_length,
                               GError **error);

Reads the MIDI file's header and positions internal buffer pointer just behind it.

#### Parameters

midi_file | the AgsMidiFile |
buffer_length | pointer to return buffer length or `NULL` |
error | the GError pointer return location |

#### Returns

the header's bytes

Since: 3.0.0

### ags_midi_file_write_header ()

    void
    ags_midi_file_write_header (AgsMidiFile *midi_file,
                                unsigned char *buffer,
                                guint buffer_length);

Write header bytes.

#### Parameters

midi_file | the AgsMidiFile |
buffer | the buffer to write |
buffer_length | the length of the buffer |

Since: 3.0.0

### ags_midi_file_read_track_data ()

    unsigned char *
    ags_midi_file_read_track_data (AgsMidiFile *midi_file,
                                   guint *buffer_length,
                                   GError **error);

Reads the MIDI file's track data.

#### Parameters

midi_file | the AgsMidiFile |
buffer_length | pointer to return buffer length or `NULL` |
error | the GError pointer return location |

#### Returns

the track's bytes

Since: 3.0.0

### ags_midi_file_write_track_data ()

    void
    ags_midi_file_write_track_data (AgsMidiFile *midi_file,
                                    unsigned char *buffer,
                                    guint buffer_length);

### ags_midi_file_read_notation ()

    void
    ags_midi_file_read_notation (AgsMidiFile *midi_file);

### ags_mid_file_read_midi ()

    void
    ags_mid_file_read_midi (AgsMidiFile *midi_file);

### ags_midi_file_new ()

    AgsMidiFile *
    ags_midi_file_new ();

Create a new instance of AgsMidiFile

#### Returns

the new AgsMidiFile

Since: 3.0.0

## Types and Values

### AGS_MIDI_FILE_MAX_TEXT_LENGTH

    #define AGS_MIDI_FILE_MAX_TEXT_LENGTH (4096)

### AGS_MIDI_FILE_MTHD

    #define AGS_MIDI_FILE_MTHD "MThd"

### AGS_MIDI_FILE_MTRK

    #define AGS_MIDI_FILE_MTRK "MTrk"

### AGS_MIDI_FILE_DEFAULT_OFFSET

    #define AGS_MIDI_FILE_DEFAULT_OFFSET (0)

### AGS_MIDI_FILE_DEFAULT_FORMAT

    #define AGS_MIDI_FILE_DEFAULT_FORMAT (1)

### AGS_MIDI_FILE_DEFAULT_BEATS

    #define AGS_MIDI_FILE_DEFAULT_BEATS (120)

### AGS_MIDI_FILE_DEFAULT_FPS

    #define AGS_MIDI_FILE_DEFAULT_FPS (30)

### AGS_MIDI_FILE_DEFAULT_TICKS

    #define AGS_MIDI_FILE_DEFAULT_TICKS (384)

### enum AgsMidiFileStatus

#### Members

AGS_MIDI_FILE_KEY_OFF |  |
AGS_MIDI_FILE_KEY_ON |  |
AGS_MIDI_FILE_KEY_PRESSURE |  |
AGS_MIDI_FILE_CHANGE_PARAMETER |  |
AGS_MIDI_FILE_CHANGE_PROGRAM |  |
AGS_MIDI_FILE_CHANNEL_PRESSURE |  |
AGS_MIDI_FILE_CHANGE_PITCH_BEND |  |
AGS_MIDI_FILE_SYSEX |  |
AGS_MIDI_FILE_QUARTER_FRAME |  |
AGS_MIDI_FILE_SONG_POSITION |  |
AGS_MIDI_FILE_SONG_SELECT |  |
AGS_MIDI_FILE_UNDEFINED_0 |  |
AGS_MIDI_FILE_UNDEFINED_1 |  |
AGS_MIDI_FILE_TUNE_REQUEST |  |
AGS_MIDI_FILE_SYSEX_END |  |
AGS_MIDI_FILE_META_EVENT |  |

### enum AgsMidiFileFlags

#### Members

AGS_MIDI_FILE_EOF |  |
AGS_MIDI_FILE_SMTPE |  |
AGS_MIDI_FILE_DROP_FRAME |  |

### AGS_MIDI_FILE_ERROR

    #define AGS_MIDI_FILE_ERROR (ags_midi_file_error_quark())

### enum AgsMidiFileError

#### Members

AGS_MIDI_FILE_ERROR_PREMATURE_EOF |  |

### struct AgsMidiFileTrack

    struct AgsMidiFileTrack {
      GObject *sequencer;

      gchar *track_name;
      unsigned char *buffer;
    };

## Property Details

### The `“filename”` property

      “filename”                 char *

The assigned filename to perform input/output on.

Owner: AgsMidiFile

Flags: Read / Write

Default value: NULL

Since: 3.0.0