Skip to content
A Game Boy Sound System player for macOS, written in Swift
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
gameboy
gbsplayer
ostrich.xcworkspace
screenshots
.gitignore
LICENSE.txt
README.md
resources.txt

README.md

Ostrich

Ostrich is a macOS media player app for playback of Game Boy Sound System files. Under the covers, it is a Nintendo Game Boy emulator written in Swift.

This readme captures how to build and use Ostrich. For more technical details, check out my blog post on it here.

A wild Ostrich appeared

Status

Ostrich emulates both of the Game Boy's pulse wave channels, and can play back the music from about half of the Game Boy's commercial titles. The other half require emulation of cartridge memory banking, or some of the less common LR35902 instructions, which are currently unsupported. The 4-bit wave and noise channels are also currently unsupported.

Popular working titles include Tetris, Castlevania, Double Dragon, and Batman.

Building

Ostrich is built using Xcode. It uses AudioKit, an open-source audio framework. Ostrich is most recently tested using Xcode 8.3.3 (Swift 3.1), AudioKit 3.7, and macOS 10.12.5. Ostrich requires macOS 10.11 (El Capitan) or newer.

To build Ostrich:

  1. Clone this repository
  2. Download an AudioKit macOS release; note the most recently tested version above
  3. Open the Ostrich workspace, ostrich.xcworkspace, with Xcode
  4. Install the AudioKit framework to both the gameboy and gbsplayer Xcode projects as described in the AudioKit installation guide
  5. Build the gameboy project
  6. Build the gbsplayer project

Run Ostrich by running the gbsplayer project.

Usage

Run Ostrich and load a GBS file (typically with extension .gbs) using File -> Open.

Playback controls are at the bottom portion of the interface. From left to right:

  • The directional pad controls track selection and volume control:
    • Left: previous track
    • Right: next track
    • Up: volume up
    • Down: volume down
  • The select and start buttons toggle muting of pulse channels 1 and 2, respectively
  • The B and A buttons are stop and play/pause, respectively

The rest of the interface is dedicated to playback state. From top to bottom:

  • The topmost text rows are the game name, composers, and copyright owner
  • The upper and lower waveforms represent pulse channels 1 and 2, respectively
  • The light near the bottom left represents playback state: red is stopped, yellow is paused, green is playing

Note that Ostrich may be resized for your viewing pleasure.

A newborn Ostrich

Technical Details

For technical details on Ostrich, check out my blog post on it here.

Author

Ostrich is written entirely by myself, Ryan Conway. It would not have been possible without the help of Austin Zheng and the documentation of Game Boy hardware written by many and available online. Some of this documentation is captured in resources.txt.

I set out to create Ostrich with the goals of teaching myself Swift and furthering my knowledge of hardware emulation, system design, and retro game music. To those ends I believe Ostrich has been a success.

License

Ostrich is copyright 2016-2017 Ryan Conway. Its source code is released under the MIT license; see LICENSE.txt.

Ostrich uses works that others have produced and made available under the terms of different licenses:

You can’t perform that action at this time.