# BendInstrumentPitch

Bends an instrument's output pitch up or down by a specified amount.

### Synopsis

`Err BendInstrumentPitch (Item Instrument, frac16 BendFrac)`

### Description

This function sets a new pitch bend value for an Instrument, a value that is stored as part of the Instrument. This function sets the resulting pitch to the product of the Instrument's frequency and BendFrac.

This setting remains in effect until changed by another call to `BendInstrumentPitch()`. To restore the original pitch of an Instrument, pass the result of Convert32_F16(1) as BendFrac.

Use `Convert12TET_F16()` to compute a BendFrac value from an interval of semitones and cents.

This function won't bend pitch above the upper frequency limit of the instrument.

### Arguments

Instrument
  The item number of an instrument

BendFrac
  16.16 factor to multiply Instrument's normal frequency by. This is a signed value; negative values result in a negative frequency value, which is not supported by all instruments. Specify the result of Convert32_F16(1) as BendFrac to restore the Instrument's original pitch.

### Return Value

The function returns a non-negative value if successful or an error code (a negative value) if an error occurs.

### Implementation

SWI implemented in Audio folio V20.

### Associated Files

audio.h

### See Also

``Convert12TET_F16`(), ConvertPitchBend() in the Music library`