Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ShubhamPP04/Izzy/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers building Izzy Music Player from source and creating distributable DMG files.

​
Building in Xcode

The simplest way to build and run Izzy Music Player is directly from Xcode.
1

Open the project

Open the Xcode project:
open Izzy.xcodeproj
2

Select scheme

In Xcode, select the “Izzy” scheme from the scheme selector at the top of the window.
3

Build and run

Press Cmd + R to build and run the app, or click the Play button in the toolbar.

​
Building from command line

You can also build Izzy using xcodebuild from the command line: 
xcodebuild -project Izzy.xcodeproj \
           -scheme Izzy \
           -configuration Release \
           build
This builds the Release configuration of the app.

​
Creating a DMG

To create a distributable DMG file, use the provided build script.
1

Prepare the build script

Make the DMG build script executable:
chmod +x build_dmg.sh
2

Run the build script

Execute the build script:
./build_dmg.sh
This script performs the following steps:
  • Cleans previous builds
  • Builds the app using xcodebuild
  • Creates an archive
  • Exports the app
  • Bundles the Python backend and dependencies
  • Creates a DMG file
3

Locate the DMG

After successful completion, the DMG will be located at:
dist/Izzy.dmg
The script also displays the file size of the generated DMG.

​
Build process details

The build_dmg.sh script automates the entire build and packaging process:

​
Archive creation

xcodebuild -project Izzy.xcodeproj \
           -scheme Izzy \
           -configuration Release \
           -derivedDataPath build \
           -archivePath build/Izzy.xcarchive \
           archive

​
App export

xcodebuild -exportArchive \
           -archivePath build/Izzy.xcarchive \
           -exportPath build/Release \
           -exportOptionsPlist ExportOptions.plist

​
Python backend bundling

The script bundles the Python backend into the app’s Resources directory:
  • Copies ytmusic_service.py
  • Bundles the music_env virtual environment (if present)
  • Includes update files (update.json, appcast.xml, release-notes.html)

​
DMG creation

The final DMG is created using hdiutil: 
hdiutil create -volname "Izzy" \
               -srcfolder <DMG_TEMP_DIR> \
               -ov \
               -format UDZO \
               dist/Izzy.dmg
The DMG includes:
  • The Izzy.app bundle
  • A symbolic link to the Applications folder for easy installation
  • README file (if DMG_README.md exists)

​
Code signing

If you need to sign the app for distribution, set the CODESIGN_IDENTITY environment variable before running the build script: 
export CODESIGN_IDENTITY="Developer ID Application: Your Name (TEAM_ID)"
./build_dmg.sh
The script will automatically:
  • Re-sign the app bundle with your identity
  • Verify the code signature
  • Ensure the app is properly signed for distribution
Without a valid signing identity, the app will still build but users will need to bypass Gatekeeper using the xattr command.

​
Build configurations

Izzy supports two build configurations:
  • Debug - For development with debug symbols and verbose logging
  • Release - Optimized build for distribution
The build_dmg.sh script uses the Release configuration by default.

​
Troubleshooting

​
Build fails

If the build fails, check:
  1. Xcode is properly installed and up to date
  2. Command Line Tools are installed: xcode-select --install
  3. All dependencies are installed: pip install -r requirements.txt

​
App not found after build

If build/Release/Izzy.app is not found after building: 
# Check build logs for errors
xcodebuild -project Izzy.xcodeproj \
           -scheme Izzy \
           -configuration Release \
           build | tee build.log

​
Code signing errors

If code signing fails:
  1. Verify your signing identity: security find-identity -v -p codesigning
  2. Ensure CODESIGN_IDENTITY matches exactly
  3. Check that your certificates are valid and not expired

​
DMG creation fails

If hdiutil fails to create the DMG: 
# Check disk space
df -h

# Verify the app bundle exists
ls -la build/Release/Izzy.app

​
Next steps

After building the app successfully:
  • Test the app thoroughly on your system
  • Verify all features work as expected
  • Consider adding your Gemini API key in Settings for AI features
  • Report any issues on the GitHub repository

Build docs developers (and LLMs) love

Get started for freeTalk to us