GSoC 2012: Improve Banshee's Mac OS X port

Banshee's OS X port needs more love. Although a working .app Bundle exists, it is quite outdated and has some obvious bugs and flaws. Throughout this Summer, it's my task to improve on that.

Progress reports

Progress on my work (as well as on other topics) can be found at my blog:

Report #1 Report #2 Report #3 Report #4 Report #5 Final report

GSoc 2012 is over and this site is outdated!

The Instructions and Reports here are kept for legacy reason! All my GSoC patches have made it into banshee mainline (>2.5.0). Please refer to the banshee homepage for up-to-date build instructions and downloads!

Building Banshee from source on Mac OS X

NOTE: Due to a blocking bug in gtk-quartz backend, Banshee does currently crash on OS X 10.6 Snow Leopard. Right now its required to run and build from OS X 10.7 Lion.

Building on OS X is a little bit of work, since you have to compile every little dependency on your own. Where on a linux box you might use apt/zypper/rpm to install the build-dependencies, you don't have that comfort on OS X. Thats why banshee uses the bockbuild meta-buildsystem to automactically fetch and build ton's of packges/tarballs/git repos to compile everything from source.

Get Xcode4 & Compiler Tools

you have to install latest XCode4 via the Appstore. After installation, open up Xcode, select Preferences -> Downloads. Press the button next to "Command Line Tools" which says Install/Update.

Folder layout

The build-process requires some folders to be in exact relative position to each other, so I suggest you follow the same folder layout as I will propse here!

Change to your home directory, and create a main folder "banshee-dev" and cd into it:

cd $HOME
mkdir banshee-dev
cd banshee-dev/

Get bockbuild

Throughout the GSoC period, I maintain a banshee-2.4-stable bockbuild repo that can build releases from the banshee 2.4.x series. For banshee's master branch you need to checkout bockbuild from my master branch, too.

But first you have to install git for OS X. Then checkout the according bockbuild repo from github:

# stable release
git clone -b banshee-2.4-stable git://

# OR unstable, build might fail, be warned!
git clone -b master git://

Build world

This will build all necessary build tools, dependencies, mono runtime,... and so on required to build banshee.

# we are still in $HOME/banshee-dev/
# change into banshee profile directory 
cd bockbuild/profiles/banshee/

# start the build world process
./darwin -bv

This process will take "very long" (about 3 hours on my 2008 Macbook white) depending on your machine and network speed. This usually only has to be done once, its not necessary to recompile the world everytime you compile banshee.

Get & build Banshee

Release builds

If you want to create a distributable .app-Bundle or just build banshee from source without modifying banshee's source code, release build is for you. The release build fetches the latest stable series (currently 2.4) from git and builds it.

cd $HOME/banshee-dev/bockbuild/profiles/banshee
./darwin -bvr

If everything completes successfully, go ahead and read section build an .app Bundle

Non-release builds

With Non-release builds you fetch the banshee source from git yourself, allowing to chose which branch or version. This is what you want if you want to start hacking the banshee sourcecode, or just feel to be to cool for release builds.

# change into working dir
cd $HOME/banshee-dev/

# fetch sourcecode

# stable 2.4 branch
# requires bockbuild-2.4-stable branch
git clone -b stable-2.4 git://

# OR
# unstable master branch - might require bockbuild master, be warned!
git clone -b master git://

#prepare build
cd banshee/

# IMPORTANT: include necessary environment variables
source ./darwin.env

# start the build

# this will NOT install banshee system wide but into its own build-root
make install

NOTE: Non-release builds include some packages absent in release build due to licensing/patent restriction (i.e. the lame mp3 encoder). Do not distribute non-release builds including such protected packages and do not create official gnome packages from non-release builds!

If everything went well, you can start banshee for the first time:

cd $HOME/banshee-dev/banshee/

# once again make sure all environment variables are set
source ./darwin.env

cd bin/
mono Banshee.exe --uninstalled

(optional) get and build the banshee-community-plugins

You can build some extension only available from the banshee community repo. Currently not all extension work for the Mac OS X platform.

TODO This currently only works with the non-release builds.

# change working dir
cd $HOME/banshee-dev/

# fetch source from git
git clone

# prepare build
cd banshee-community-extensions

# IMPORTANT: include environment variables
source ./darwin.env

# start the build

# this will not install it system wide, but into our own build-root
make install

# ONLY FOR non-release builds
# if everything went fine, copy the extensions to banshee's bin/ directory
cp bin/* $HOME/banshee-dev/banshee/bin/

(optional) Hacking the Code with MonoDevelop

First, get and install MonoDevelop from the MonoDevelop website To write all necessary environment variables into MonoDevelop's .csproj file, you can do:

cd $HOME/banshee-dev/bockbuild/profiles/banshee
./  --csproj-insert=$HOME/banshee-dev/banshee/src/Clients/Nereid/Nereid.csproj

Now just open the $HOME/banshee/Banshee.sln file from within MonoDevelop and you are ready to hack and even debug banshee using a first-class IDE.

Get latest pre-build alpha .app-Bundle for Mac

These builds are preview alpha quality and contain very obvious bugs. Do not report bug's regarding those builds, yet. The bundles do not run from anywhere else than the /Applications folder, so you have to drag them there before running.

The bundles include some plugins from the banshee-community-repositories, which have to be enabled via the settings menu.

NOTE: Due to a bug in gtk-quartz these bundles will crash on OS X 10.6 (Snow Leopard) or earlier. It is therefore required to run on OS X 10.7 Lion.

Banshee-2.4.1-osx-alpha1.dmg (obsolete)

Banshee-2.4.1-osx-alpha2.dmg (obsolete, enabled keyboard shortcuts)

Banshee-2.4.1-osx-alpha3.dmg (obsolete, added USB mass storage hardware support, enabled UPnP/DLNA)

Banshee-2.4.1-osx-alpha4.dmg (obsolete, network shares as mass storage support, native file open dialogs)

Banshee-2.4.1-osx-alpha5.dmg (obsolete, open media files from finder, fix muted volume button) (Final GSoC binary, contains all patches & enhancements)

Please note that there will be no future releases posted here, but on the official download page.


If you see weird boxes instead of fonts, or banshee crashes on startup or at a later time, try these steps first (to be entered in Terminal):

  • remove you banshee configuration:

        rm -rf $HOME/.config/banshee-1
  • remove possible corrupt gstreamer data from earlier installations:

        rm -rf $HOME/.gstreamer-0.10/

Outreach/SummerOfCode/2012/Projects/TimoDoerr_Banshee_MacOSX (last edited 2013-12-03 18:33:52 by WilliamJonMcCann)