Troubleshooting

Troubleshooting

Start with:

bash scripts/verify.sh

It detects missing tools, generated-project drift, formatting and lint errors, build failures, test failures, and invalid icon bundle metadata.

Full Xcode was not found

Command Line Tools alone cannot build Cadence:

export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"
xcodebuild -version

Adjust the path if the Xcode application has a different name.

A development tool is missing

brew bundle

The generated project changed

project.yml is authoritative:

xcodegen generate --spec project.yml
git diff -- Cadence.xcodeproj

Commit the generated project only when the source configuration changed.

Cadence cannot create its library

Confirm that macOS allows Cadence to access the Music folder and that ~/Music is writable. Do not disable App Sandbox or add broad entitlements as a workaround.

Files do not appear in Import Review

• verify the audio extension is supported;
• add the file or containing folder again;
• check the duplicate classification;
• keep an LRC beside its audio with a matching normalized basename.

Remember that Scan and Review do not copy files.

Playback is silent or uses another backend

• inspect Audio Path in Now Playing;
• check the selected routing profile and output device;
• verify the managed file still exists;
• test built-in Mac output before Bluetooth, AirPlay, multichannel, or spatial routes.

Lyrics do not follow playback

The LRC needs valid line timestamps such as [01:23.45]. Plain text can be displayed and edited but cannot follow playback.

Recovering a deleted item

Open Cadence Trash and use Restore. Empty Trash permanently removes managed copies and the restore manifest; it does not delete original imported files.

Reporting a problem

Open a focused GitHub issue with a synthetic reproduction. Remove personal media, metadata, paths, artwork, and lyrics. Use the private security route for vulnerabilities.