# CreateInstrument

Creates an instrument using a template.

### Synopsis

`Item CreateInstrument (Item InsTemplate, const TagArg *tagList)
Item CreateInstrumentVA (Item InsTemplate, uint32 tag1, ...)`

### Description

This function allocates an Instrument based on an instrument Template, previously loaded using `LoadInsTemplate()` or similar call, and allocates the DSP resources necessary for the Instrument. See also the convenience function `LoadInstrument()` which combines these two steps.

The new instrument is always created in the AF_STOPPED state, regardless of the setting of AF_INSF_ABANDONED.

Call `DeleteInstrument()` when you're finished with the Instrument to deallocate its resources.

This function is a superset of `AllocInstrument()`.

### Arguments

InsTemplate
  Item number of a loaded instrument template used to allocate the instrument.

### Tags

AF_TAG_CALCRATE_DIVIDE
  (uint32) (new tag for V24) Create. Specifies the the denominator of the fraction of the total DSP cycles on which this instrument is to run. The only valid settings at this time are 1 to run on all DSP cycles (i.e. execute at 44,100 cycles/sec) and 2 to run on only 1/2 of the DSP cycles (i.e. execute at 22,050 cycles/sec). Defaults to 1.

AF_TAG_PRIORITY
  (uint32) Priority of new instrument in range of 0..255. Defaults to 100.

AF_TAG_SET_FLAGS
  (uint32) Set of AF_INSF_ flags to set in new instrument. All flags default to cleared. See the Instrument item page a for complete description of AF_INSF_ flags.

### Return Value

The function returns the item number for the Instrument (a positive value) or an error code (a negative value) if an error occurs.

### Implementation

Folio call implemented in Audio folio V24.

### Associated Files

audio.h

### See Also

``DeleteInstrument`(), AllocInstrument(), LoadInsTemplate(), LoadInstrument()`