IpatchSF2

IpatchSF2 — SoundFont instrument file object

Stability Level

Stable, unless otherwise indicated

Functions

Properties

char * author Read / Write
char * comment Read / Write
char * copyright Read / Write
char * date Read / Write
char * engine Read / Write
char * name Read / Write
char * product Read / Write
char * rom-name Read / Write
char * rom-version Read / Write
gboolean samples-24bit Read / Write
char * software Read / Write
char * version Read / Write

Types and Values

Object Hierarchy

    GObject
    ╰── IpatchItem
        ╰── IpatchContainer
            ╰── IpatchBase
                ╰── IpatchSF2

Description

SoundFont version 2 instrument file object. Parent to IpatchSF2Preset, IpatchSF2Inst and IpatchSF2Sample objects.

Functions

ipatch_sf2_new ()

IpatchSF2 *
ipatch_sf2_new (void);

Create a new SoundFont base object.

Returns

New SoundFont base object with a reference count of 1. Caller owns the reference and removing it will destroy the item.


ipatch_sf2_get_presets()

#define             ipatch_sf2_get_presets(sfont)

ipatch_sf2_get_insts()

#define             ipatch_sf2_get_insts(sfont)

ipatch_sf2_get_samples()

#define             ipatch_sf2_get_samples(sfont)

ipatch_sf2_set_file ()

void
ipatch_sf2_set_file (IpatchSF2 *sf,
                     IpatchSF2File *file);

Sets the file object of a SoundFont. SoundFont files are kept open for sample data that references the file. This function sets a SoundFonts authoritive file object. A convenience function, as ipatch_base_set_file() does the same thing (albeit without more specific type casting).

Parameters

sf

SoundFont to set file object of

 

file

File object to use with the SoundFont.

 

ipatch_sf2_get_file ()

IpatchSF2File *
ipatch_sf2_get_file (IpatchSF2 *sf);

Gets the file object of a SoundFont. The returned SoundFont file object's reference count has incremented. The caller owns the reference and is responsible for removing it with <function>g_object_unref()</function>. A convenience function as ipatch_base_get_file() does the same thing (albeit without more specific type casting).

Parameters

sf

SoundFont to get file object of

 

Returns

The SoundFont file object or NULL if sf is not open. Remember to unref the file object with <function>g_object_unref()</function> when done with it.

[transfer full]


ipatch_sf2_get_info ()

char *
ipatch_sf2_get_info (IpatchSF2 *sf,
                     IpatchSF2InfoType id);

Get a SoundFont info string by RIFF FOURCC ID.

Parameters

sf

SoundFont to get info from

 

id

RIFF FOURCC id

 

Returns

New allocated info string value or NULL if no info with the given id . String should be freed when finished with it.


ipatch_sf2_set_info ()

void
ipatch_sf2_set_info (IpatchSF2 *sf,
                     IpatchSF2InfoType id,
                     const char *val);

Set SoundFont info. Validates id and ensures val does not exceed the maximum allowed length for the given info type.

Emits changed signal on SoundFont.

Parameters

sf

SoundFont to set info of

 

id

RIFF FOURCC id

 

val

Value to set info to or NULL to unset (clear) info.

 

ipatch_sf2_get_info_array ()

IpatchSF2Info *
ipatch_sf2_get_info_array (IpatchSF2 *sf);

Get all string info (not IPATCH_SF2_VERSION or IPATCH_SF2_ROM_VERSION) from a SoundFont object. The array is sorted in the order recommended by the SoundFont standard for saving.

[skip]

Parameters

sf

SoundFont to get all info strings from

 

Returns

A newly allocated array of info structures terminated by an array member with 0 valued <structfield>id</structfield> field. Remember to free the array with ipatch_sf2_free_info_array() when finished with it.


ipatch_sf2_free_info_array ()

void
ipatch_sf2_free_info_array (IpatchSF2Info *array);

Frees an info array returned by ipatch_sf2_get_info_array().

[skip]

Parameters

array

SoundFont info array

 

ipatch_sf2_info_id_is_valid ()

gboolean
ipatch_sf2_info_id_is_valid (guint32 id);

Check if a given RIFF FOURCC id is a valid SoundFont info id.

[skip]

Parameters

id

RIFF FOURCC id (see IpatchSF2InfoType)

 

Returns

TRUE if id is a valid info id, FALSE otherwise


ipatch_sf2_get_info_max_size ()

int
ipatch_sf2_get_info_max_size (IpatchSF2InfoType infotype);

Get maximum chunk size for info chunks.

NOTE: Max size includes terminating NULL character so subtract one from returned value to get max allowed string length.

[skip]

Parameters

infotype

An info enumeration

 

Returns

Maximum info chunk size or 0 if invalid infotype . Subtract one to get max allowed string length (if returned value was not 0).


ipatch_sf2_find_preset ()

IpatchSF2Preset *
ipatch_sf2_find_preset (IpatchSF2 *sf,
                        const char *name,
                        int bank,
                        int program,
                        const IpatchSF2Preset *exclude);

Find a preset by name or bank:preset MIDI numbers. If preset name and bank :program are specified then match for either condition. If a preset is found its reference count is incremented before it is returned. The caller is responsible for removing the reference with g_object_unref() when finished with it.

Parameters

sf

SoundFont to search in

 

name

Name of preset to find or NULL to match any name.

[nullable]

bank

MIDI bank number of preset to search for or -1 to not search by MIDI bank:program numbers

 

program

MIDI program number of preset to search for, only used if bank is 0-128

 

exclude

A preset to exclude from the search or NULL.

[nullable]

Returns

The matching preset or NULL if not found. Remember to unref the item when finished with it.

[transfer full]


ipatch_sf2_find_inst ()

IpatchSF2Inst *
ipatch_sf2_find_inst (IpatchSF2 *sf,
                      const char *name,
                      const IpatchSF2Inst *exclude);

Find an instrument by name in a SoundFont. If a matching instrument is found, its reference count is incremented before it is returned. The caller is responsible for removing the reference with g_object_unref() when finished with it.

Parameters

sf

SoundFont to search in

 

name

Name of Instrument to find

 

exclude

An instrument to exclude from the search or NULL.

[nullable]

Returns

The matching instrument or NULL if not found. Remember to unref the item when finished with it.

[transfer full]


ipatch_sf2_find_sample ()

IpatchSF2Sample *
ipatch_sf2_find_sample (IpatchSF2 *sf,
                        const char *name,
                        const IpatchSF2Sample *exclude);

Find a sample by name in a SoundFont. If a sample is found its reference count is incremented before it is returned. The caller is responsible for removing the reference with g_object_unref() when finished with it.

Parameters

sf

SoundFont to search in

 

name

Name of sample to find

 

exclude

A sample to exclude from the search or NULL.

[nullable]

Returns

The matching sample or NULL if not found. Remember to unref the item when finished with it.

[transfer full]


ipatch_sf2_get_zone_references ()

IpatchList *
ipatch_sf2_get_zone_references (IpatchItem *item);

Get list of zones referencing an IpatchSF2Inst or IpatchSF2Sample.

Parameters

item

Item to locate referencing zones of, must be of type IpatchSF2Inst or IpatchSF2Sample and be parented to an IpatchSF2 object.

 

Returns

New object list containing IpatchSF2Zone objects that refer to item . The new list object has a reference count of 1 which the caller owns, unreference to free the list.

[transfer full]


ipatch_sf2_make_unique_name ()

char *
ipatch_sf2_make_unique_name (IpatchSF2 *sfont,
                             GType child_type,
                             const char *name,
                             const IpatchItem *exclude);

Generates a unique name for the given child_type in sfont . The name parameter is used as a base and is modified, by appending a number, to make it unique (if necessary). The exclude parameter is used to exclude an existing sfont child item from the search.

MT-Note: To ensure that an item is actually unique before being added to a SoundFont object, ipatch_container_add_unique() should be used.

Parameters

sfont

SoundFont item

 

child_type

A child type of sfont to search for a unique name in

 

name

An initial name to use or NULL.

[nullable]

exclude

An item to exclude from search or NULL.

[nullable]

Returns

A new unique name which should be freed when finished with it.

Types and Values

enum IpatchSF2Flags

Members

IPATCH_SF2_SAMPLES_24BIT

SoundFont 24 bit samples enabled flag

 

IPATCH_SF2_UNUSED_FLAG_SHIFT

#define IPATCH_SF2_UNUSED_FLAG_SHIFT (IPATCH_BASE_UNUSED_FLAG_SHIFT + 3)

enum IpatchSF2InfoType

Members

IPATCH_SF2_UNKNOWN

   

IPATCH_SF2_VERSION

   

IPATCH_SF2_ENGINE

   

IPATCH_SF2_NAME

   

IPATCH_SF2_ROM_NAME

   

IPATCH_SF2_ROM_VERSION

   

IPATCH_SF2_DATE

   

IPATCH_SF2_AUTHOR

   

IPATCH_SF2_PRODUCT

   

IPATCH_SF2_COPYRIGHT

   

IPATCH_SF2_COMMENT

   

IPATCH_SF2_SOFTWARE

   

IPATCH_SF2_INFO_COUNT

#define IPATCH_SF2_INFO_COUNT 11

IPATCH_SF2_DEFAULT_ENGINE

#define IPATCH_SF2_DEFAULT_ENGINE "EMU8000"

Property Details

The “author” property

  “author”                   char *

Author of SoundFont.

Owner: IpatchSF2

Flags: Read / Write

Default value: NULL


The “comment” property

  “comment”                  char *

Comments.

Owner: IpatchSF2

Flags: Read / Write

Default value: NULL


The “copyright” property

  “copyright”                char *

Copyright.

Owner: IpatchSF2

Flags: Read / Write

Default value: NULL


The “date” property

  “date”                     char *

Creation date.

Owner: IpatchSF2

Flags: Read / Write

Default value: NULL


The “engine” property

  “engine”                   char *

Sound synthesis engine identifier.

Owner: IpatchSF2

Flags: Read / Write

Default value: "EMU8000"


The “name” property

  “name”                     char *

SoundFont name.

Owner: IpatchSF2

Flags: Read / Write

Default value: NULL


The “product” property

  “product”                  char *

Product SoundFont is intended for.

Owner: IpatchSF2

Flags: Read / Write

Default value: NULL


The “rom-name” property

  “rom-name”                 char *

ROM name identifier.

Owner: IpatchSF2

Flags: Read / Write

Default value: NULL


The “rom-version” property

  “rom-version”              char *

ROM version "major.minor".

Owner: IpatchSF2

Flags: Read / Write

Default value: NULL


The “samples-24bit” property

  “samples-24bit”            gboolean

Enable 24 bit samples.

Owner: IpatchSF2

Flags: Read / Write

Default value: FALSE


The “software” property

  “software”                 char *

Software 'created by:modified by'.

Owner: IpatchSF2

Flags: Read / Write

Default value: NULL


The “version” property

  “version”                  char *

SoundFont version ("major.minor").

Owner: IpatchSF2

Flags: Read / Write

Default value: "2.01"

See Also

IpatchSF2Preset, IpatchSF2Inst, IpatchSF2Sample