AgsMidiBuilder: Advanced Gtk+ Sequencer Audio Reference Manual

AgsMidiBuilder

AgsMidiBuilder — MIDI builder

Stability Level

Stable, unless otherwise indicated

Functions

#define	AGS_MIDI_BUILDER_GET_OBJ_MUTEX()
#define	AGS_MIDI_BUILDER_HEADER()
#define	AGS_MIDI_BUILDER_TRACK()
AgsMidiBuilderHeader *	ags_midi_builder_header_alloc ()
void	ags_midi_builder_header_free ()
AgsMidiBuilderTrack *	ags_midi_builder_track_alloc ()
void	ags_midi_builder_track_free ()
GList *	ags_midi_builder_track_find_delta_time_with_track_name ()
void	ags_midi_builder_track_insert_midi_message ()
guchar *	ags_midi_builder_track_get_delta_time_offset ()
void	ags_midi_builder_midi_putc ()
void	ags_midi_builder_on_error ()
void	ags_midi_builder_append_header ()
void	ags_midi_builder_append_track ()
void	ags_midi_builder_append_key_on ()
void	ags_midi_builder_append_key_off ()
void	ags_midi_builder_append_key_pressure ()
void	ags_midi_builder_append_change_parameter ()
void	ags_midi_builder_append_change_pitch_bend ()
void	ags_midi_builder_append_change_program ()
void	ags_midi_builder_append_change_pressure ()
void	ags_midi_builder_append_sysex ()
void	ags_midi_builder_append_quarter_frame ()
void	ags_midi_builder_append_song_position ()
void	ags_midi_builder_append_song_select ()
void	ags_midi_builder_append_tune_request ()
void	ags_midi_builder_append_sequence_number ()
void	ags_midi_builder_append_smtpe ()
void	ags_midi_builder_append_tempo ()
void	ags_midi_builder_append_time_signature ()
void	ags_midi_builder_append_key_signature ()
void	ags_midi_builder_append_sequencer_meta_event ()
void	ags_midi_builder_append_text_event ()
void	ags_midi_builder_append_xml_node ()
void	ags_midi_builder_from_xml_doc ()
void	ags_midi_builder_build ()
void	ags_midi_builder_open_filename ()
guchar *	ags_midi_builder_get_data ()
guchar *	ags_midi_builder_get_data_with_length ()
void	ags_midi_builder_write ()
AgsMidiBuilder *	ags_midi_builder_new ()
AgsMidiBuilder *	ags_midi_builder_new_from_filename ()

Properties

gpointer

file

Read / Write

Signals

void	append-header	Run Last
void	append-track	Run Last
void	change-channel-pressure	Run Last
void	change-parameter	Run Last
void	change-pitch-bend	Run Last
void	change-program	Run Last
void	key-off	Run Last
void	key-on	Run Last
void	key-pressure	Run Last
void	key-signature	Run Last
void	midi-putc	Run Last
void	on-error	Run Last
void	quarter-frame	Run Last
void	sequence-number	Run Last
void	sequencer-meta-event	Run Last
void	smtpe	Run Last
void	song-position	Run Last
void	song-select	Run Last
void	sysex	Run Last
void	tempo	Run Last
void	text-event	Run Last
void	time-signature	Run Last
void	tune-request	Run Last

Types and Values

enum	AgsMidiBuilderFlags
struct	AgsMidiBuilderHeader
struct	AgsMidiBuilderTrack

Object Hierarchy

    GObject
    ╰── AgsMidiBuilder

Includes

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

Description

The AgsMidiBuilder lets you create MIDI files using its builder functions.

Functions

AGS_MIDI_BUILDER_GET_OBJ_MUTEX()

#define AGS_MIDI_BUILDER_GET_OBJ_MUTEX(obj) (&(((AgsMidiBuilder *) obj)->obj_mutex))

AGS_MIDI_BUILDER_HEADER()

#define AGS_MIDI_BUILDER_HEADER(ptr) ((AgsMidiBuilderHeader *)(ptr))

AGS_MIDI_BUILDER_TRACK()

#define AGS_MIDI_BUILDER_TRACK(ptr) ((AgsMidiBuilderTrack *)(ptr))

ags_midi_builder_header_alloc ()

AgsMidiBuilderHeader *
ags_midi_builder_header_alloc ();

Allocate MIDI builder header.

Returns

the newly allocated AgsMidiBuilderHeader.

[type gpointer][transfer none]

Since: 3.0.0

ags_midi_builder_header_free ()

void
ags_midi_builder_header_free (AgsMidiBuilderHeader *midi_builder_header);

Free MIDI builder header.

Parameters

midi_builder_header

the AgsMidiBuilderHeader.

[type gpointer][transfer none]

Since: 3.0.0

ags_midi_builder_track_alloc ()

AgsMidiBuilderTrack *
ags_midi_builder_track_alloc ();

Allocate MIDI builder track.

Returns

the newly allocated AgsMidiBuilderTrack.

[type gpointer][transfer none]

Since: 3.0.0

ags_midi_builder_track_free ()

void
ags_midi_builder_track_free (AgsMidiBuilderTrack *midi_builder_track);

Free MIDI builder track.

Parameters

midi_builder_track

the AgsMidiBuilderTrack.

[type gpointer][transfer none]

Since: 3.0.0

ags_midi_builder_track_find_delta_time_with_track_name ()

GList *
ags_midi_builder_track_find_delta_time_with_track_name
                               (GList *midi_builder_track,
                                guint64 absolute_time,
                                gchar *track_name);

Finds matching AgsMidiBuilderTrack within midi_builder_track GList.

Parameters

midi_builder_track	the AgsMidiBuilderTrack.	[element-type gpointer][transfer none]
absolute_time	the absolute time
track_name	the track's string representation

Returns

the matching GList.

[element-type gpointer][transfer none]

Since: 3.0.0

ags_midi_builder_track_insert_midi_message ()

void
ags_midi_builder_track_insert_midi_message
                               (AgsMidiBuilderTrack *midi_builder_track,
                                guchar *buffer,
                                guint length);

Insert MIDI message.

Parameters

midi_builder_track	the AgsMidiBuilderTrack
buffer	the MIDI message
length	the buffer length

Since: 3.0.0

ags_midi_builder_track_get_delta_time_offset ()

guchar *
ags_midi_builder_track_get_delta_time_offset
                               (AgsMidiBuilderTrack *midi_builder_track,
                                guint64 absolute_time);

Get offset by delta time.

Parameters

midi_builder_track	the AgsMidiBuilderTrack
absolute_time	the absolute time

Returns

the buffer position before delta_time

Since: 3.0.0

ags_midi_builder_midi_putc ()

void
ags_midi_builder_midi_putc (AgsMidiBuilder *midi_builder,
                            gint c);

Put char in MIDI file.

Parameters

midi_builder	the AgsMidiBuilder
c	the character to put

Since: 3.0.0

ags_midi_builder_on_error ()

void
ags_midi_builder_on_error (AgsMidiBuilder *midi_builder,
                           GError **error);

Triggered as an error occurs.

Parameters

midi_builder	the AgsMidiBuilder
error	the error

Since: 3.0.0

ags_midi_builder_append_header ()

void
ags_midi_builder_append_header (AgsMidiBuilder *midi_builder,
                                guint offset,
                                guint format,
                                guint track_count,
                                guint division,
                                guint times,
                                guint bpm,
                                guint clicks);

Appends MIDI header to midi_builder .

Parameters

midi_builder	the AgsMidiBuilder
offset	start delta-time
format	either 0, 1 or 2.
track_count	the number of tracks
division	timing division
times	pulse per quarter note
bpm	beats per minute
clicks	timing clicks

Since: 3.0.0

ags_midi_builder_append_track ()

void
ags_midi_builder_append_track (AgsMidiBuilder *midi_builder,
                               gchar *track_name);

Append a track called track_name to midi_builder .

Parameters

midi_builder	the AgsMidiBuilder
track_name	the track name

Since: 3.0.0

ags_midi_builder_append_key_on ()

void
ags_midi_builder_append_key_on (AgsMidiBuilder *midi_builder,
                                guint delta_time,
                                guint audio_channel,
                                guint note,
                                guint velocity);

Append key-on for note to midi_builder with key dynamics velocity , at delta_time .

Parameters

midi_builder	the AgsMidiBuilder
delta_time	delta-time
audio_channel	the audio channel
note	the note to play from 0 to 128
velocity	key dynamics

Since: 3.0.0

ags_midi_builder_append_key_off ()

void
ags_midi_builder_append_key_off (AgsMidiBuilder *midi_builder,
                                 guint delta_time,
                                 guint audio_channel,
                                 guint note,
                                 guint velocity);

Append key-off for note to midi_builder with key dynamics velocity , at delta_time .

Parameters

midi_builder	the AgsMidiBuilder
delta_time	delta-time
audio_channel	the audio channel
note	the note to play from 0 to 128
velocity	key dynamics

Since: 3.0.0

ags_midi_builder_append_key_pressure ()

void
ags_midi_builder_append_key_pressure (AgsMidiBuilder *midi_builder,
                                      guint delta_time,
                                      guint audio_channel,
                                      guint note,
                                      guint pressure);

Append key-pressure for note to midi_builder with key dynamics pressure , at delta_time .

Parameters

midi_builder	the AgsMidiBuilder
delta_time	delta-time
audio_channel	the audio channel
note	the note to play from 0 to 128
pressure	key dynamics

Since: 3.0.0

ags_midi_builder_append_change_parameter ()

void
ags_midi_builder_append_change_parameter
                               (AgsMidiBuilder *midi_builder,
                                guint delta_time,
                                guint channel,
                                guint control,
                                guint value);

Appends change parameter.

Parameters

midi_builder	the AgsMidiBuilder
delta_time	the delta time
channel	the channel
control	the control
value	the value

Since: 3.0.0

ags_midi_builder_append_change_pitch_bend ()

void
ags_midi_builder_append_change_pitch_bend
                               (AgsMidiBuilder *midi_builder,
                                guint delta_time,
                                guint channel,
                                guint transmitter);

Change pitch bend.

Parameters

midi_builder	the AgsMidiBuilder
delta_time	the delta time
channel	the channel
transmitter	the transmitter

Since: 3.0.0

ags_midi_builder_append_change_program ()

void
ags_midi_builder_append_change_program
                               (AgsMidiBuilder *midi_builder,
                                guint delta_time,
                                guint channel,
                                guint program);

Appends change program.

Parameters

midi_builder	the AgsMidiBuilder
delta_time	the delta time
channel	the channel
program	the program

Since: 3.0.0

ags_midi_builder_append_change_pressure ()

void
ags_midi_builder_append_change_pressure
                               (AgsMidiBuilder *midi_builder,
                                guint delta_time,
                                guint channel,
                                guint pressure);

Appends change pressure.

Parameters

midi_builder	the AgsMidiBuilder
delta_time	the delta time
channel	the channel
pressure	the pressure

Since: 3.0.0

ags_midi_builder_append_sysex ()

void
ags_midi_builder_append_sysex (AgsMidiBuilder *midi_builder,
                               guint delta_time,
                               guchar *sysex_data,
                               guint length);

Appends sysex data.

Parameters

midi_builder	the AgsMidiBuilder
delta_time	the delta time
sysex_data	the sysex data
length	length

Since: 3.0.0

ags_midi_builder_append_quarter_frame ()

void
ags_midi_builder_append_quarter_frame (AgsMidiBuilder *midi_builder,
                                       guint delta_time,
                                       guint message_type,
                                       guint values);

Appends quarter frame.

Parameters

midi_builder	the AgsMidiBuilder
delta_time	the delta time
message_type	the message type
values	values

Since: 3.0.0

ags_midi_builder_append_song_position ()

void
ags_midi_builder_append_song_position (AgsMidiBuilder *midi_builder,
                                       guint delta_time,
                                       guint song_position);

Appends song position.

Parameters

midi_builder	the AgsMidiBuilder
delta_time	the delta time
song_position	the song position

Since: 3.0.0

ags_midi_builder_append_song_select ()

void
ags_midi_builder_append_song_select (AgsMidiBuilder *midi_builder,
                                     guint delta_time,
                                     guint song_select);

Appends song select.

Parameters

midi_builder	the AgsMidiBuilder
delta_time	the delta time
song_select	the song select

Since: 3.0.0

ags_midi_builder_append_tune_request ()

void
ags_midi_builder_append_tune_request (AgsMidiBuilder *midi_builder,
                                      guint delta_time);

Appends tune request.

Parameters

midi_builder	the AgsMidiBuilder
delta_time	the delta time

Since: 3.0.0

ags_midi_builder_append_sequence_number ()

void
ags_midi_builder_append_sequence_number
                               (AgsMidiBuilder *midi_builder,
                                guint delta_time,
                                guint sequence);

Appends sequence number.

Parameters

midi_builder	the AgsMidiBuilder
delta_time	the delta time
sequence	the sequence number

Since: 3.0.0

ags_midi_builder_append_smtpe ()

void
ags_midi_builder_append_smtpe (AgsMidiBuilder *midi_builder,
                               guint delta_time,
                               guint rr,
                               guint hr,
                               guint mn,
                               guint se,
                               guint fr);

Appends smtpe.

Parameters

midi_builder	the AgsMidiBuilder
delta_time	the delta time
rr	rate
hr	hours
mn	minutes
se	seconds
fr	fraction

Since: 3.0.0

ags_midi_builder_append_tempo ()

void
ags_midi_builder_append_tempo (AgsMidiBuilder *midi_builder,
                               guint delta_time,
                               guint tempo);

Appends tempo.

Parameters

midi_builder	the AgsMidiBuilder
delta_time	the delta time
tempo	the tempo

Since: 3.0.0

ags_midi_builder_append_time_signature ()

void
ags_midi_builder_append_time_signature
                               (AgsMidiBuilder *midi_builder,
                                guint delta_time,
                                guint nn,
                                guint dd,
                                guint cc,
                                guint bb);

Appends time signature.

Parameters

midi_builder	the AgsMidiBuilder
delta_time	the delta time
nn	numerator
dd	denominator
cc	ticks per metronome click
bb	32nd per quarter note

Since: 3.0.0

ags_midi_builder_append_key_signature ()

void
ags_midi_builder_append_key_signature (AgsMidiBuilder *midi_builder,
                                       guint delta_time,
                                       guint sf,
                                       guint mi);

Appends key signature.

Parameters

midi_builder	the AgsMidiBuilder
delta_time	the delta time
sf	key
mi	mode

Since: 3.0.0

ags_midi_builder_append_sequencer_meta_event ()

void
ags_midi_builder_append_sequencer_meta_event
                               (AgsMidiBuilder *midi_builder,
                                guint delta_time,
                                guint len,
                                guint id,
                                guint data);

Appends sequencer meta event.

Parameters

midi_builder	the AgsMidiBuilder
delta_time	the delta time
len	the length
id	the id
data	the data

Since: 3.0.0

ags_midi_builder_append_text_event ()

void
ags_midi_builder_append_text_event (AgsMidiBuilder *midi_builder,
                                    guint delta_time,
                                    gchar *text,
                                    guint length);

Appends text event.

Parameters

midi_builder	the AgsMidiBuilder
delta_time	the delta time
text	the string
length	the string length

Since: 3.0.0

ags_midi_builder_append_xml_node ()

void
ags_midi_builder_append_xml_node (AgsMidiBuilder *midi_builder,
                                  xmlNode *node);

Append from XML node node .

Parameters

midi_builder	the AgsMidiBuilder
node	the xmlNode

Since: 3.0.0

ags_midi_builder_from_xml_doc ()

void
ags_midi_builder_from_xml_doc (AgsMidiBuilder *midi_builder,
                               xmlDoc *doc);

Builds from XML document doc .

Parameters

midi_builder	the AgsMidiBuilder
doc	the xmlDocument

Since: 3.0.0

ags_midi_builder_build ()

void
ags_midi_builder_build (AgsMidiBuilder *midi_builder);

Build the MIDI data.

Parameters

midi_builder

the AgsMidiBuilder

Since: 3.0.0

ags_midi_builder_open_filename ()

void
ags_midi_builder_open_filename (AgsMidiBuilder *midi_builder,
                                gchar *filename);

Open filename and assign FILE stream to midi_builder .

Parameters

midi_builder	the AgsMidiBuilder
filename	the filename

Since: 3.2.0

ags_midi_builder_get_data ()

guchar *
ags_midi_builder_get_data (AgsMidiBuilder *midi_builder);

Get SMF data of midi_builder .

Parameters

midi_builder

the AgsMidiBuilder

Returns

the SMF data

Since: 3.2.0

ags_midi_builder_get_data_with_length ()

guchar *
ags_midi_builder_get_data_with_length (AgsMidiBuilder *midi_builder,
                                       guint *length);

Get SMF data of midi_builder .

Parameters

midi_builder	the AgsMidiBuilder
length	the length of data.	[out]

Returns

the MIDI data as array.

[transfer full]

Since: 3.7.24

ags_midi_builder_write ()

void
ags_midi_builder_write (AgsMidiBuilder *midi_builder);

Write data of midi_builder to file.

Parameters

midi_builder

the AgsMidiBuilder

Since: 3.2.0

ags_midi_builder_new ()

AgsMidiBuilder *
ags_midi_builder_new ();

Creates a new instance of AgsMidiBuilder

Returns

the new AgsMidiBuilder

Since: 3.0.0

ags_midi_builder_new_from_filename ()

AgsMidiBuilder *
ags_midi_builder_new_from_filename (gchar *filename);

Creates a new instance of AgsMidiBuilder

Parameters

filename

the filename.

[nullable]

Returns

the new AgsMidiBuilder

Since: 3.2.0

Types and Values

enum AgsMidiBuilderFlags

Members

AGS_MIDI_BUILDER_EOF
AGS_MIDI_BUILDER_EOT

struct AgsMidiBuilderHeader

struct AgsMidiBuilderHeader {
  AgsMidiBuilder *midi_builder;

  guint offset;
  guint format;
  guint count;
  guint division;
  guint times;
  guint beat;
  guint clicks;

  guchar *data;
  guint length;
};

struct AgsMidiBuilderTrack

struct AgsMidiBuilderTrack {
  AgsMidiBuilder *midi_builder;

  guint offset;
  gchar *track_name;

  guint64 absolute_time;

  guchar *data;
  guint length;
};

Property Details

The `“file”` property

  “file”                     gpointer

The file to parse data from.

Owner: AgsMidiBuilder

Flags: Read / Write

Since: 3.0.0

Signal Details

The `“append-header”` signal

void
user_function (AgsMidiBuilder *midi_builder,
               guint           offset,
               guint           format,
               guint           track_count,
               guint           division,
               guint           times,
               guint           bpm,
               guint           clicks,
               gpointer        user_data)

The ::append-header signal is emited during building of header.

Parameters

midi_builder	the builder
offset	start delta-time
format	format 0, 1 or 2
track_count	the number of tracks
division	timing division
times	pulses per quarter note
bpm	beats per minute
clicks	timing clicks
user_data	user data set when the signal handler was connected.

Flags: Run Last

Since: 3.0.0

The `“append-track”` signal

void
user_function (AgsMidiBuilder *midi_builder,
               char           *track_name,
               gpointer        user_data)

The ::append-track signal is emited during building of track.

Parameters

midi_builder	the builder
track_name	the trach name
user_data	user data set when the signal handler was connected.

Flags: Run Last

Since: 3.0.0

The `“change-channel-pressure”` signal

void
user_function (AgsMidiBuilder *agsmidibuilder,
               guint           arg1,
               guint           arg2,
               guint           arg3,
               gpointer        user_data)

Flags: Run Last

The `“change-parameter”` signal

void
user_function (AgsMidiBuilder *agsmidibuilder,
               guint           arg1,
               guint           arg2,
               guint           arg3,
               guint           arg4,
               gpointer        user_data)

Flags: Run Last

The `“change-pitch-bend”` signal

void
user_function (AgsMidiBuilder *agsmidibuilder,
               guint           arg1,
               guint           arg2,
               guint           arg3,
               gpointer        user_data)

Flags: Run Last

The `“change-program”` signal

void
user_function (AgsMidiBuilder *agsmidibuilder,
               guint           arg1,
               guint           arg2,
               guint           arg3,
               gpointer        user_data)

Flags: Run Last

The `“key-off”` signal

void
user_function (AgsMidiBuilder *agsmidibuilder,
               guint           arg1,
               guint           arg2,
               guint           arg3,
               guint           arg4,
               gpointer        user_data)

Flags: Run Last

The `“key-on”` signal

void
user_function (AgsMidiBuilder *agsmidibuilder,
               guint           arg1,
               guint           arg2,
               guint           arg3,
               guint           arg4,
               gpointer        user_data)

Flags: Run Last

The `“key-pressure”` signal

void
user_function (AgsMidiBuilder *agsmidibuilder,
               guint           arg1,
               guint           arg2,
               guint           arg3,
               guint           arg4,
               gpointer        user_data)

Flags: Run Last

The `“key-signature”` signal

void
user_function (AgsMidiBuilder *agsmidibuilder,
               guint           arg1,
               guint           arg2,
               gboolean        arg3,
               gpointer        user_data)

Flags: Run Last

The `“midi-putc”` signal

void
user_function (AgsMidiBuilder *midi_builder,
               int             error,
               gpointer        user_data)

The ::midi-putc signal is emited during putting char to file.

Parameters

midi_builder	the builder
error	the GError
user_data	user data set when the signal handler was connected.

Flags: Run Last

Since: 3.0.0

The `“on-error”` signal

void
user_function (AgsMidiBuilder *midi_builder,
               gpointer        error,
               gpointer        user_data)

The ::on-error signal is emited during building of event.

Parameters

midi_builder	the builder
error	the GError
user_data	user data set when the signal handler was connected.

Flags: Run Last

Since: 3.0.0

The `“quarter-frame”` signal

void
user_function (AgsMidiBuilder *agsmidibuilder,
               guint           arg1,
               guint           arg2,
               guint           arg3,
               gpointer        user_data)

Flags: Run Last

The `“sequence-number”` signal

void
user_function (AgsMidiBuilder *agsmidibuilder,
               guint           arg1,
               guint           arg2,
               gpointer        user_data)

Flags: Run Last

The `“sequencer-meta-event”` signal

void
user_function (AgsMidiBuilder *agsmidibuilder,
               guint           arg1,
               guint           arg2,
               guint           arg3,
               guint           arg4,
               gpointer        user_data)

Flags: Run Last

The `“smtpe”` signal

void
user_function (AgsMidiBuilder *agsmidibuilder,
               guint           arg1,
               guint           arg2,
               guint           arg3,
               guint           arg4,
               guint           arg5,
               guint           arg6,
               gpointer        user_data)

Flags: Run Last

The `“song-position”` signal

void
user_function (AgsMidiBuilder *agsmidibuilder,
               guint           arg1,
               guint           arg2,
               gpointer        user_data)

Flags: Run Last

The `“song-select”` signal

void
user_function (AgsMidiBuilder *agsmidibuilder,
               guint           arg1,
               guint           arg2,
               gpointer        user_data)

Flags: Run Last

The `“sysex”` signal

void
user_function (AgsMidiBuilder *agsmidibuilder,
               guint           arg1,
               gpointer        arg2,
               guint           arg3,
               gpointer        user_data)

Flags: Run Last

The `“tempo”` signal

void
user_function (AgsMidiBuilder *agsmidibuilder,
               guint           arg1,
               guint           arg2,
               gpointer        user_data)

Flags: Run Last

The `“text-event”` signal

void
user_function (AgsMidiBuilder *agsmidibuilder,
               guint           arg1,
               char           *arg2,
               guint           arg3,
               gpointer        user_data)

Flags: Run Last

The `“time-signature”` signal

void
user_function (AgsMidiBuilder *agsmidibuilder,
               guint           arg1,
               guint           arg2,
               guint           arg3,
               guint           arg4,
               guint           arg5,
               gpointer        user_data)

Flags: Run Last

The `“tune-request”` signal

void
user_function (AgsMidiBuilder *agsmidibuilder,
               guint           arg1,
               gpointer        user_data)

Flags: Run Last