# Attachment

The binding of a sample or an envelope to an instrument.

### Description

An attachment is the item to binds a sample or an envelope to a particular instrument.

An Attachment is associated with precisely one Envelope and one Instrument, or one Sample and one Instrument. An Attachment is said to be an Envelope Attachment if it is attached to an Envelope, or a Sample Attachment if attached to a Sample.

Sample attachments actually come in two flavors: one for input FIFOs and another for output FIFOs, defined by the Hook to which the Sample is attached. Both kinds are considered Sample Attachments and no distinction is made between them.

A single Instrument can have one Envelope Attachment per Envelope hook and one Sample Attachment per Output FIFO. A single Instrument can have multiple Sample Attachments per Input FIFO, but only one will be selected to be played when the instrument is started. This is useful for creating multi-sample instruments, where the sample selected to be played depends on the pitch to be played.

A single Sample or Envelope can have multiple Attachments made to it.

### Folio

audio

### Item Type

AUDIO_ATTACHMENT_NODE

### Create

`AttachSample`(), AttachEnvelope(), CreateItem()

### Delete

`DetachSample`(), DetachEnvelope(), DeleteItem()

### Modify

SetAudioItemInfo()

### Use

`LinkAttachments`(), MonitorAttachment(), ReleaseAttachment(), StartAttachment(), StopAttachment(), WhereAttachment()

### Tags

AF_TAG_CLEAR_FLAGS
  (uint32) Modify. Set of AF_ATTF_ flags to clear. Clears every flag for which a 1 is set in ta_Arg. See also AF_TAG_SET_FLAGS. The final state of any flag is determined by the last occurrence of that flag in a AF_TAG_SET_FLAGS or AF_TAG_CLEAR_FLAGS.

AF_TAG_ENVELOPE
  (Item) Create. Envelope Item to attach to Instrument. Exactly one of AF_TAG_ENVELOPE or AF_TAG_SAMPLE must be specified.

AF_TAG_HOOKNAME
  (const char *) Create. The name of the sample or envelope hook in the instrument to attach to. For sample hooks, defaults to the first one listed for each instrument. For envelopes, defaults to "Env".

AF_TAG_INSTRUMENT
  (Item) Create. Instrument or Template item to attach envelope or sample to. Must be specified when creating an Attachment.

AF_TAG_SAMPLE
  (Item) Create. Sample Item to attach to instrument. Exactly one of AF_TAG_ENVELOPE or AF_TAG_SAMPLE must be specified.

AF_TAG_SET_FLAGS
  (uint32) Create, Modify. Set of AF_ATTF_ flags to set. Sets every flag for which a 1 is set in ta_Arg. See also AF_TAG_CLEAR_FLAGS. The final state of any flag is determined by the last occurrence of that flag in a AF_TAG_SET_FLAGS or AF_TAG_CLEAR_FLAGS.

AF_TAG_START_AT
  (int32) Create, Modify. Specifies the point at which to start when the attachment is started (with `StartAttachment()` or `StartInstrument()``)` .

For sample attachments, specifies a sample frame number in the sample at which to begin playback.

For envelopes, attachments specifies the segment index at which to start.

AF_TAG_TIME_SCALE
  (ufrac16) Create. Scales all of the times in the attached envelopes by the supplied ufrac16. Defaults to 1.0. Only applies to envelope attachments.

### Flags

AF_ATTF_FATLADYSINGS
  If set, causes the instrument to stop when the attachment finishes playing. This bit can be used to mark the one or more envelope(s) or sample(s) that are considered to be the determiners of when the instrument is completely done. For envelopes, the default setting for this flag comes from the AF_ENVF_FATLADYSINGS flag. Defaults to cleared for samples.

AF_ATTF_NOAUTOSTART
  When set, causes `StartInstrument()` to not automatically start this attachment. This allows later starting of the attachment by using `StartAttachment()`. Defaults to cleared (attachment defaults to starting when instrument is started).