> ## Documentation Index
> Fetch the complete documentation index at: https://chart-spec.enchor.us/llms.txt
> Use this file to discover all available pages before exploring further.

# convertChart()

```ts theme={null}
function convertChart(
   song, 
   format, 
   options?
): {
  report: ConversionReport;
  song: SongDocument;
};
```

Converts a song's chart to the other format and returns the converted song with a report, leaving `song` as it was
(r5 Q10). The report reads the converted song back: each track's TrackHash is kept or changed, with its cause.

* **To `.mid`:** each instrument's phrases are its Expert track's (r4 Q4), and zero-length phrases stay zero-length.
  song.ini gets the settings `.mid` needs: `multiplier_note` when a solo would otherwise read as star power, and
  `sustain_cutoff_threshold` only when a sustain would otherwise be trimmed, as the largest value that keeps every
  sustain (r4 Q5). The `.chart` `[Song]` Offset, PreviewStart and PreviewEnd, which games read only from a `.chart`,
  are copied into song.ini when it doesn't set them.
* **To `.chart`:** vocal pitches, harmonies, and MIDI-only tracks and events such as the venue are left out; lyrics
  and vocal phrases are kept. `[Song]` agrees with song.ini.

song.ini is otherwise kept as written (D4). Throws `ConversionError` for a value the target can't store, unless
`force` is set, and then writes the nearest one; a resolution over 32767 has none.

## Parameters

| Parameter | Type |
| - | - |
| `song` | [`SongDocument`](https://chart-spec.enchor.us/scan-chart/api/index/interfaces/SongDocument) |
| `format` | [`ChartFormat`](https://chart-spec.enchor.us/scan-chart/api/index/type-aliases/ChartFormat) |
| `options?` | \{ `force?`: `boolean`; } |
| `options.force?` | `boolean` |

## Returns

```ts theme={null}
{
  report: ConversionReport;
  song: SongDocument;
}
```

| Name | Type |
| - | - |
| `report` | [`ConversionReport`](https://chart-spec.enchor.us/scan-chart/api/index/interfaces/ConversionReport) |
| `song` | [`SongDocument`](https://chart-spec.enchor.us/scan-chart/api/index/interfaces/SongDocument) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.