Head Chef 1 User Guide · Chapter 26

Troubleshooting

Applies to Head Chef 1.0 and later 1.x releases

This chapter helps you find and fix problems by what you see or hear. Each section starts with a table: find your symptom or the exact message Head Chef shows, read the likely cause, and follow what to do. Messages in bold are quoted exactly as Head Chef shows them, on the status line, in the footer at the bottom of the window, or in the window you are using.

Most messages appear in the footer with a Dismiss button. When a message is too long for the footer, point at it to read all of it.

Most audio settings live in the Audio Engine window. Open it with Settings > Audio Engine… or ⌘,.

Sound and devices #

Symptom	Likely cause	What to do
You hear nothing, or the sound comes from the wrong speakers	Head Chef plays through a different device	In Settings > Audio Engine…, choose your interface in Output Device, or System Default Output to follow macOS, and click Apply.
Your interface is not in the Output Device list	It was connected after Head Chef started	Click Refresh Devices, choose it, and click Apply.
The list shows Unavailable Audio Output	The device chosen earlier is disconnected	Reconnect it, or choose another device.
Connect an audio output device, then press Play again.	No output device is available	Connect an interface or headphones, then press Play.
You still hear nothing	A track is muted, another is soloed, or Main is low	Check M and S on your tracks and the Main fader in Mix. A fader at its bottom is -60 dB, not silent, so a channel can be very quiet without being muted.
The Audio Engine window says the session and the device run at different rates	The device is set to another sample rate	Head Chef switches the device to the session rate when you press Play, if the device supports it.
This output device does not support a rate, or Set your output device to a rate in Audio MIDI Setup, then press Play again.	The device cannot switch to the session rate	Set the rate in Audio MIDI Setup, choose another device, or use a session at a rate the device supports.
The output device has not switched to a rate	The device took too long to change rate	Check the device in Audio MIDI Setup and press Play again.
The clock line shows Clock drift warning, or The audio device clock differs too much from the session rate. Check Audio MIDI Setup or choose another output, then press Play again.	The device's clock runs too far from the session rate	Check the interface's clock source and connections. When it is steady, the line reads Clock locked.
The output device changed. Stop, then press Play again. or The output device or its sample rate changed. Stop, then press Play again.	The device was unplugged, replaced or changed rate during playback	Stop, reconnect or check the device, and press Play.
The audio device stopped. Reconnect it and press Play again.	The interface stopped delivering audio	Reconnect the interface, then press Play.
The output buffer size changed. Stop, then press Play again.	Another app changed the device's buffer	Stop and press Play.
Crackles, clicks or dropouts	The Mac cannot fill each audio buffer in time; see buffer size	Choose a larger Buffer Size, for example 512 Samples or 1024 Samples, and click Apply. Turn off or remove heavy plugins.
A delay between playing and hearing	A large buffer adds latency	Choose a smaller Buffer Size, such as 128 Samples, while you record. The window shows Input, Output and round-trip latency for the buffer you choose.
32 and 64 sample buffers minimize monitoring latency but increase real-time CPU load.	You chose a very small buffer	Use it only if your Mac plays without crackles.
Could not refresh audio devices. or The audio engine configuration could not be applied.	macOS did not answer the request	Try again. If it keeps failing, reconnect the device or restart Head Chef.
A level above full scale distorts in your speakers	Head Chef's mix carries overs, but the output to the interface stops at full scale	Lower the Main fader until the Main meter stays out of the red. See Mixing.

Head Chef does not show a dropout counter or a processor meter. If you hear crackles, raise the buffer size first.

Recording #

Symptom	Likely cause	What to do
Save your session before recording.	The session has never been saved	Choose File > Save Session. Takes are stored next to the session file.
Arm one empty mono audio track to record a take.	No track, or more than one, is armed	Arm exactly one empty audio track.
Record a mono take in an empty session. Create a new session and add an empty audio track.	Existing backing has no matching Head Chef input monitor on the armed destination	Choose Input or Auto monitoring on that empty mono destination to record over the song. Without Head Chef input monitoring, use a saved empty session. See Monitoring.
Choose a recording input for the armed track.	The track has no input	Click the track's input button and choose an input.
The selected input is unavailable. Reconnect it or choose another input. or the header reads Input unavailable	The interface for the saved input is disconnected	Reconnect it and click Refresh inputs, or choose another input.
Match the session and input sample rates before recording.	The interface runs at another rate	Set the interface to the session rate in Audio MIDI Setup, or record into a session at the interface's rate.
Microphone access is off. Allow Head Chef microphone access before recording.	macOS blocks Head Chef from inputs	See Microphone access below.
Keep or dismiss the recovered take before recording again.	A stopped take is waiting	Click Recovery… and choose Keep take or Dismiss.
Input clipped. Reduce the interface input gain.	The input is too loud	Turn down the gain on your interface and record again.
You cannot hear yourself while recording	Head Chef does not monitor inputs	Use your interface's direct monitoring. See Monitoring.
The status line shows Recording stopped. with a reason	The input, the interface, the disk or the click output failed during the take	Follow the reason shown, then keep or dismiss the take. When a take stops on its own lists each reason.
Stop recording or cancel record readiness before changing the session.	You tried to edit while Head Chef records or waits to record	Finish or cancel the take first.

Microphone access #

macOS asks you to allow microphone access the first time Head Chef uses an input. The Audio Engine window shows the current state after Microphone access:

Shown	What to do
Allowed	Nothing; Head Chef can record.
Not requested yet. Head Chef asks the first time you enable an input.	Click Enable input in the Mono recording input window.
Blocked. Allow Head Chef in System Settings > Privacy & Security > Microphone.	Turn on Head Chef under Privacy & Security > Microphone in System Settings, then click Refresh inputs.
Restricted on this Mac by a device policy.	Ask the person who manages the Mac.
No input device is available.	Connect an interface or microphone, then click Refresh Devices.

Playback and performance #

Symptom	Likely cause	What to do
The status line shows Preparing playback… with a percentage	Instruments render their parts before playback	Wait, or click Cancel. Playback starts when preparation finishes.
Playback could not start. followed by a reason	Preparing the audio failed	Follow the reason; most ask you to press Play again.
Playback audio could not be read. Check disk access, then press Play or try moving the cursor again.	A session audio file could not be read	Check that the drive holding the session is connected, then press Play.
This session needs more prepared audio than can be kept at once. Shorten the session or use fewer instruments, then press Play again.	The session's instruments need more memory than Head Chef keeps for playback	Shorten the song or remove instrument tracks you do not need.
Instruments are being prepared. Wait for preparation to finish or cancel it before playing.	A preparation is still running	Wait for it, or cancel it.
Stop input monitoring before preparing this playback position.	Software input monitoring is active while a third-party plugin needs preparation at the new position	Turn off software input monitoring, choose the position again and wait for preparation. See Play from another point.
Head Chef feels slow	Too much processing for the buffer size	Raise Buffer Size, and turn off or remove plugins you are not using.
This session can hold up to 128 source channels.	The session reached its source-track limit	See the limits below. Remove tracks you no longer need.

Performance and memory #

Supported imported audio stays on disk with no fixed combined file-size allowance. Leave enough free space for imported audio, conversion work and saved copies. Playback and editing still need available memory and disk bandwidth.

Each session has fixed limits so playback stays reliable:

Limit	Value
Source tracks	128
Effect Returns	4
MIDI notes	2,048 per clip and 16,384 per session
Clip gain points	1,024 per clip
Undo steps	512, within 64 MiB

When a session gets close to a limit, Head Chef refuses the change and tells you, for example A session can hold up to 16384 MIDI notes. or This session can hold up to four aux channels.

Plugins #

Symptom	Likely cause	What to do
A plugin stopped responding. Save your session, then press Play to restore its saved sound, or remove it.	A third-party plugin crashed or hung	Save, then press Play. If the plugin keeps failing, remove it from the channel.
A plugin stopped. Press Play to restore its saved sound, or remove it.	The same, reported from its window	Press Play, or remove the plugin.
A plugin you installed is not in the Plugin Browser	Head Chef has not scanned it, or it is in a folder Head Chef does not search	Click Rescan, or add its folder; see Scan for plugins again.
The browser says a number of plugins could not load	They failed the scan	Click Details to see each plugin and its reason, then retry them with Retry blocked plugins.
The plugin could not be scanned. Try again.	A scan failed	Click Rescan.
Plugin search could not start. Try Rescan again.	The scan could not begin	Click Rescan.
The plugin folder could not be saved. Check the path and try again.	The folder path is not valid	Choose the folder with Browse… instead of typing it.
Cannot read plugin folder followed by its path	Head Chef cannot open the folder	Check the folder's permissions in Finder.
Plugin folders contain too many files. Choose a more specific folder.	A folder you added holds too much	Add the folder that contains your plugins, not a whole drive.
Use up to eight plugins on each channel.	The channel is full	Move effects to another channel or an Effect Return.
The Plugin window could not open window appears	The plugin's window could not open, or a sound could not be loaded	Read the message in the window, then open the plugin again from its channel.
Close a plugin window before opening another.	Too many plugin windows are open	Close a plugin window you are not using.
This plugin has changed. Scan it again before using this sound.	The plugin was updated since its last scan	Click Rescan.
An ARA 2 editor shows The ARA plugin is still analysing this clip. Wait for it to finish, then Apply.	The editor has not finished reading the clip	Wait, then click Apply.
Apply or cancel the open ARA edit before continuing.	An ARA edit is open	Apply or cancel it first. See Plugins.

Scan for plugins again #

Head Chef scans the standard plugin folders. Rescan after you install, update or remove a plugin.

Click Plugins in the toolbar, or choose View > Plugin Browser.
Click Rescan. The button shows Scanning… until the scan finishes.

To add a folder or retry plugins that failed earlier:

Select a channel, then click Folders… in the Plugin Browser.
Click Edit Folders…. Keep Search standard folders on, and add a folder with Browse… or by typing its path and clicking Add Folder.
To try plugins that failed in an earlier scan, turn on Retry blocked plugins.
Click Rescan.

Sessions and files #

A session does not open #

Symptom	Likely cause	What to do
This is not a valid Head Chef session.	The file is not a Head Chef session, or it is damaged	Open a backup copy if you have one.
A message starting Cannot open audio:	The session's hidden audio folder is missing or was moved	Put the folder back next to the session file; see Where Head Chef keeps your work.
The session audio has changed. Restore its original media file.	An audio file in the session folder was edited or replaced	Restore the original file from a backup.
This session document is too large.	The file is larger than Head Chef can open	Open a backup, or split the material across sessions.
Wait for the mix render to finish, or cancel it before replacing this session.	Render Mix is running	Wait for it, or click Cancel Render.
A project from another music app does not open	The file is damaged or its audio is missing	Open it from its original folder, with its audio folders beside it. See Importing.

Saving and importing #

Symptom	Likely cause	What to do
That file already exists. Choose a different name.	A file with that name is in the folder	Choose another name.
A message starting Cannot save session: or Cannot save audio:	The folder is read-only or the disk is full	Save to a folder you can write to, and free disk space.
Save changes to this session?	The session has unsaved changes	Choose Save, Don't Save or Cancel.
Choose audio at the session rate of a rate Hz or use the import sample-rate options.	The import did not choose a sample-rate conversion	Choose File > Import Audio…, then Resample imported audio to project rate. See Importing.
Unsupported or corrupted audio file. Choose a WAV, BWF, AIFF, FLAC, MP3, M4A/AAC, CAF or Ogg file.	The file is damaged or in another format	Convert the file in another app first.
Audio import failed. Try the files again.	Reading a file failed	Import the files again.
Wait for the current audio import to finish, or cancel it.	An import is running	Wait, or click Cancel import in the footer.
Choose files within the session's 128 source-channel limit.	The import would pass 128 tracks	Import fewer files.

MIDI devices #

Symptom	Likely cause	What to do
Playing a keyboard makes no sound	No instrument track is selected, or input is off	Select an instrument track. Click MIDI in the toolbar and check that input is ON. The panel shows Select an instrument track to play live when no instrument track is selected.
Your keyboard is not listed	It was connected while the list was open	Click Refresh Ports in the MIDI panel.
Selected keyboard is offline: switch to All Connected Keyboards (Auto) or reconnect it.	The keyboard you chose is disconnected	Reconnect it, or choose All Connected Keyboards (Auto) under Keyboard Source.
A keyboard plays nothing on one channel	The MIDI Channel filter is set to another channel	Choose All Channels (Omni).
A note keeps sounding	A note-off was lost	Click All Notes Off.
MIDI keyboard input buffer overflowed; held notes were released.	The keyboard sent more data than Head Chef could take	Release the keys and play again.
Your control surface is not offered as a keyboard	Its MIDI input is reserved for the surface	Use a separate keyboard. See Control surfaces and assistants.
In the Mini Bar panel, No MIDI inputs are available. Connect a device and refresh.	No MIDI device is connected	Connect a keyboard, then choose Refresh MIDI inputs under MIDI.
In the Mini Bar panel, MIDI input stopped. Refresh and reconnect it. or The selected MIDI input disconnected. Reconnect it and try again.	The keyboard was unplugged	Reconnect it, then choose it again under MIDI.
Disconnect MIDI input before playing the software keyboard.	The Mini Bar panel has a MIDI input connected	Choose Disconnect input under MIDI, or play from the MIDI keyboard.

Rendering #

Symptom	Likely cause	What to do
The mix exceeds the range for integer WAV. Reduce the level or choose 32-bit float. No output file was published.	A peak passed 0 dBFS in a PCM format	Lower the Main fader or the loudest channels, or choose 32-bit float. See Rendering your mix.
A mix render is already running. Wait for it or cancel it first.	One render runs at a time	Wait, or click Cancel Render.
That file already exists. Choose a different name.	A file with that name is in the folder	Choose another name.
A message starting Could not write the mix. Choose a writable folder:	The folder is read-only or the disk is full	Choose another folder, or free disk space.
Choose None for dither when rendering 32-bit float WAV.	Dither does not apply to float files	Set Dither to None, or choose a PCM format.
The mix is too long for a WAV file.	The song is longer than a WAV file can hold	Shorten the song, or split it across sessions and render each part.
The status line shows Render failed	Rendering stopped with an error	Read the message below it, fix the cause and render again.
Changes after rendering started are not included.	You edited during the render	Render again to include the changes.
A clip you muted with `⌘M` is in the rendered file	Render Mix plays muted clips	Mute the track instead before you render. See Editing audio.
A loudness value reads Below loudness gate or Less than a time	The file is too quiet or too short to measure	Nothing is wrong with the file. See Rendering your mix.

Jam #

Symptom	Likely cause	What to do
Choose an input to record.	No input is chosen for your part	Choose and connect an input under JAM ALONG before you click ● REC.
Roll an idea before holding a backing part. or Roll an idea first.	The jam has no idea yet	Roll an idea first. See Jam.
These holds do not fit a new starting point. followed by the conflicting parts	The parts you hold cannot be combined with a new roll	Release one of the named holds and roll again.
No previous roll is available. or Already at the earliest retained roll.	There is nothing earlier to return to	Roll forward instead.
Add or record musical material before saving this Jam.	The jam is empty	Roll an idea or record a part, then click Save Jam.
Jam could not be saved. Your changes are still here.	Saving failed	Try Save Jam again.
Current Jam has unsaved changes. Choose Save, Discard changes, or Cancel.	You started or opened another jam	Choose what to do with the current jam.
Add or record musical material before using this Jam in Studio.	The jam is empty	Add material first, then click the Studio transfer button.
Select at least one part or recording to print to tracks.	Nothing is selected in the Studio transfer button	Select the parts and recordings to send.
Transfer could not be completed. Destination Session is unchanged.	Sending to Studio failed	Try again. Your Studio session has not changed.

Control surfaces and assistants #

Symptom	Likely cause	What to do
The surface does not move or respond	It is not enabled, or not in the right mode	Choose Settings > Control Surface…, set the surface to its DAW control mode, choose its ports, and click Enable. The status reads Connected when it works.
Your surface is missing from the port lists	It was connected after the window opened	Click Refresh Ports.
Select both a MIDI input and a MIDI output.	Only one port is chosen	Choose the surface under both MIDI input and MIDI output.
The MIDI ports could not be opened. Refresh the port list and select available ports.	The ports are in use or gone	Click Refresh Ports and choose the ports again.
The MIDI input disconnected. Reconnect it and enable the control surface again. or The MIDI output disconnected. Reconnect it and enable the control surface again.	The surface was unplugged	Reconnect it and click Enable.
Touch this fader before moving it.	The surface reports moves without a touch	Touch the fader, then move it.
Finish the touched fader before changing mute or solo.	You pressed Mute or Solo while holding a fader	Let go of the fader first.
Your assistant app says it cannot reach Head Chef	Head Chef is not running, or the connection is set up wrong	Open Head Chef first, then check the command in your assistant app. See Connect an AI assistant.
The session changed. Read its current state and try again.	The session changed between reading it and editing it	Try the action again.

Where Head Chef keeps your work #

When you save a session, Head Chef writes:

the session file, ending in .headchef, where you choose;
a hidden .headchef-media folder next to it, holding the session's audio;
a hidden .headchef-recordings folder next to it, holding what you record.

Keep these together. To move or back up a session, move or copy the whole folder that contains them. Finder hides folders whose names start with a dot; press ⇧⌘. in Finder to show them.

Clip fades, clip mute, clip lock and sync points are kept only while Head Chef is open; they are not saved in the session file. See Editing audio.

Get help #

Help > Head Chef 1 User Guide opens this guide online.
Help > Keyboard Shortcuts… lists every shortcut and lets you search them; see Keyboard shortcuts.
For anything else, contact bitsnacks support at bitsnacks.com/support. Include the exact message Head Chef showed, what you were doing, your macOS version and the audio interface you use.