Ambient OSX

An Eccentric MP3 Player — For Mac OSX

1. General Information

This page describes Mac OSX edition of Ambient, version 1.1, dated 22-August-2009.

Ambient is an eccentric MP3 music player program. It is derived from an earlier application developed several years ago for Linux, updated and ported to the Mac OSX Cocoa framework. If you are interested in the Linux version, please see that page for that at

The official source for Ambient OSX is maintained at:

Unlike it's older brother on Linux, this version includes an executable binary for Intel Macs so you won't have to build it yourself, but it's intended as a source code distribution, open sourced under the MIT license.

Bug reports, flames, questions and other feedback should be directed to:

2. Background

Ambient is an MP3 music player program. It was created for two purposes. First, to give me a music player that satisfied my own admittedly somewhat eccentric feature desires. Second, to teach myself about Mac OSX application development in the Cocoa environment.

The idea for Ambient came about years ago because I bought a big disk drive, ripped my CD collection (about 400 discs) and found myself with 6,000 or so MP3 files on my hands. The various MP3 player programs I tried out seemed to waste a lot of code on useless features like "skins" while not giving you a great handle on managing a big collection of music files (this was way before the advent of iTunes, which, though loaded with cool features, I still find unsatisfactory on a number of dimensions). Also, the way the MP3 world has developed, there seems to be a strong bias towards thinking of individual songs as the granularity of packaging, whereas CDs and other traditional recording media are structured around the album. This is not to say that the album is a better way to organize music, but simply that that is the way the corpus at hand is already structured artistically so it makes sense to be able to think of things that way when you want to. Finally, I wanted a way to characterize the music in my collection according to various traits that correspond more to mood than to genre: I mostly listen to music while working, and I find that the kind of music that is good for coding by is entirely different from the kind of music that good for debugging by, which is in turn entirely different from the kind of music that is good for writing by, and so on. So I wanted a program that I could just instruct, for example, "I'm debugging now" and have it queue up appropriate material. Then when I shift to writing, tell it so and have it seamlessly shift the mood of what it's playing accordingly. That's a big part of what Ambient does.

3. Installation

1. Download the Ambient distribution image from

2. Mount the image, extract the contents.

3. If you want simply to use the application, a binary is right there on top for you. If you want to build it yourself (presumably after tinkering with the insides), the folder ambient-macosx-1.1 contains sources and an XCode project file.

4. Put the executable in your Applications folder, if you dare.

4. Supported Platforms

This program has been tested on and is known to work on (and indeed is used daily on) various versions of Mac OSX, up to the latest as of this writing, 10.5.8. At this point, I suspect it won't quite work on versions older than Leopard (10.5).

There is also a Linux version that uses GTK. Information about this can be had at Note that the Mac distribution encompasses nearly all of the Linux source files as well, but you'll need the Linux distribution if you actually want to build the thing under Linux, as there are various ancillary files you will also need.

5. Use

(This is a fairly terse and somewhat disorganized summary of the operation of Ambient. Eventually I ought to produce superior documentation, but in the interest of not further delaying its public release I'm going to let it go with just this for now.)

5.1 What it does

Ambient is an MP3 player. It sits on top of a collection of MP3 files, shows you what's there, and lets you play stuff. There are three sources of information that Ambient uses to manage the MP3 collection:

The basic operation of Ambient is:

1. Read the .amb file (usually)
2. Do stuff (e.g., play music)
3. Write the .amb file (usually)
4. Exit

Naturally, all of the interesting activity happens in step 2. What actually happens depends on the command line options Ambient is started with, but broadly speaking, there are batch mode operations and there is interactive mode. Interactive mode, in turn, can interact with you via one of two different UIs: text or GUI. However, the Mac version is primarily oriented towards the GUI and to start it in command line mode you'll actually need to go inside the application bundle to the executable directly (for the adventurous, that's

5.2 The data model

Ambient's model of the world is a three-level hierarchy of artist/album/track. The MP3 collection is a directory containing one sub-directory for each artist. Each of these in turn contains a directory for each of that artist's albums, which in turn contain a set of .mp3 files for the individual tracks on the album. Artist and album directory names are generated from the artist's or album's name by mapping all "funny" characters (basically, everything except alphanumerics, period (`.'), hyphen (`-') and comma (`,')) to underscore (`_') but preserving letter case. The .mp3 file names are generated from the track title using a name of the form NN.TITLE.mp3, where NN is the 2-digit track number and TITLE is the title of the track mapped the same way artist and album names are mapped.

For example, one little bit of my file hierarchy has:


Note that this hierarchy and set of name mapping rules is the natural form produced by the CD ripping program I use, Grip (, or at least it was when I stared using it. Grip has in the meantime changed its name mapping rules slightly, but I've not yet modified Ambient correspondingly. (If you are using a newer version of Grip you may need to do some manual file renaming to make Ambient happy; sorry.) And yes, I know that Grip is not a Mac application. A big item on my todo list Mac version is to revise Ambient to make direct use of iTunes' metadata and music files.

5.2.1 Comma mangling

Ambient maintains a more legible representation of this hierarchy in its database. It remembers the unmangled form of the artist, album and track names and generates the file names for the .mp3 files as it needs them. Actually, that's not 100% true. Ambient treats commas in artist and album names as a special case. Ambient's GUI presents these in alphabetic order, but before actually displaying them it rearranges stuff between commas for legibility. Thus:

Mozart, Wolfgang Amadeus
Nuclear Whales Saxophone Orchestra, The

display as:

Wolfgang Amadeus Mozart
The Nuclear Whales Saxophone Orchestra

respectively, but alphabetize in the Ms and Ns rather than the Ws and Ts. The comma rearrangement rules also allow for embedding with two commas:

Petty, Tom, And The Heartbreakers

displays as:

Tom Petty And The Heartbreakers

but alphabetizes in the Ps instead of the Ts. Finally, the case where a comma legitimately appears in a name is handled by appending an extra comma on the end of the name. Thus the album title

Past, Present And Future

which would incorrectly render as:

Present And Future Past

can be forced to display properly by stating its title as:

Past, Present And Future,

Yes, this is a hack.

5.3 Using Ambient with Grip and CDDB

As I mentioned above, I rip CDs using Grip. Grip makes use of the CDDB database at (*see footnote). When you feed a CD to Grip, the first thing it does is query FreeDB using the CDDB protocol, which more often than not will return a listing of the disc's artist, album and track information, saving you the trouble of entering it all yourself (though you will often have to fix typos, spelling errors and creative use of letter case before using this data -- you are dealing here with the Internet hive mind at its simultaneous best and worst). If the CDDB query doesn't turn up any data, then you just have to enter it all yourself after all. Also, I locally modify the artist and album names to follow the comma-mangling conventions described above, which differ from FreeDB's preferred rules for naming things. In any case, the information about the CD is saved in a file which Grip maintains (normally in the directory ~/.cddb).

[*footnote: <rant>Alas, the original CDDB database at has been usurped by a company called Gracenote, who have asserted private ownership over the collective product of thousands of individual Internet users who cooperatively contributed to the CD database over the years. This is one of the uglier sides of the Internet revolution, the bald-faced seizure of assets by people whose position seems to be that they can get away with it because nobody else's individual interest is large enough to justify the cost of stopping them. These people are thieves and you ought not to associate with them. </rant>]

Ambient gets its notion of the names of things, as well as other information such as track lengths, by reading the files in Grip's CDDB cache. This is how you tell Ambient about the arrival of new files in the MP3 collection: you tell it to reread the CDDB cache, from which it will update its .amb file accordingly.

5.4 Actually using Ambient

5.4.1 Some general concepts

Ambient has two ways of deciding what it should play: stepping through a playlist, or selecting randomly based on "mood".

The playlist is fairly straightforward. It's just a list of tracks to play. You can add to it by selecting individual tracks, whole albums, or an artist's entire corpus. Once in the playlist, entries can also be selectively removed, or the whole list shuffled or cleared.

The entire "mood" mechanism, on the other hand, is a bit peculiar and requires further explanation. The desire to have this mechanism is what motivated my writing Ambient in the first place. The basic idea is that there is a collection of "moods", which are simply symbolic attribute tags that you can define and then attach to particular tracks, albums or artists. You can do a search of the music collection by tag or by an arbitrary boolean expression of tags; the result of the search can be examined to satisfy your curiosity or it can be added to the playlist. Finally, and most importantly, you can indicate a tag as an "ambient mood" (or, once again, a boolean expression of tags) to the program and it will select tracks at random that match that tag and play them (and though the tracks will play in random order, they won't repeat until they've all been played). This is good for situations that just want to have appropriate background music, like programming or writing.

A couple of other minor features:

You can link one track to another, so that selecting the first track for play will automatically select the track it is linked to as well. Multiple tracks can be chained together in this fashion. This is useful for something like a symphony, which is typically spread over multiple tracks but really wants to be treated as a single unit (unless you are the kind of person who always prefers listening to selected individual movements, which I'm not).

You can mark tracks as "don't play". This will prevent Ambient from playing the track when it is told to play the larger collection (album or artist) that contains that track. This is mainly useful for telling it to avoid things like CD-ROM tracks which don't actually correspond to files in the MP3 collection. It's also useful for skipping empty tracks that record producers sometimes put in when trying to be artsy (for example, on The Why Store's eponymous 27-track CD, tracks 13 through 26 are empty for no obvious reason). In fact, when taking in new info from the CDDB cache, Ambient will automatically mark any track entitled CD-ROM Track or Empty as "don't play", though you can undo this if somebody actually created music with one of those titles. You can also use the "don't play" feature to skip the occasional utterly horrible abomination that sometimes crops up in the midst of otherwise reasonable music (my prototypical example of this phenomenon being the Pet Shop Boys' piece "The sound of the atom splitting" which appears on the first disc of their "Alternative" album. This is a disc which I otherwise adore, but this particular track makes me involuntarily jump out of my chair while my blood pressure spikes dangerously; in a way it's actually a remarkable artistic achievement, but I don't want to experience it again without deliberation. This one track was the spur that caused me to implement the "don't play" feature.)

5.4.2 GUI interactive mode

Ambient's normal mode of operation is via its graphical interface. The vast majority of the interface is presented in a single window that comes up when you start the program. On the Mac, it looks like this:

Ambient screenshot The music collection frame

At the top of the window is a large pane that displays the music collection, sorted alphabetically by artist. You can expand a particular artist by clicking on the line containing their name. If you double-click on an artist or click on the triangle, the list expands to include that artist's albums, which in turn can be selected by clicking on them or expanded via double-click into lists of the tracks on those albums. You can also move the your selection up or down by using the up or down arrow keys, or scroll up and down by fiddling with the scrollbar using your mouse. You can also randomly skip to a particular artist by typing the first few characters of their (last) name. You can select multiple things at once with the shift and command keys according to the usual Mac UI conventions.

Below the music list is a frame containing controls related to whatever artist, album or track is currently selected. This frame displays summary information about the selected item: in the case of an artist, the artist's name and the number of albums; in the case of an album, the artist's name, the album name, the number of tracks, and the total playing time of all the tracks; in the case of a track, it displays the artist name, album name, track title and number, and the playing time of the track. To the right of the summary information is box showing the attached mood tags associated with the selected item, if there are any; these may be individually selected by clicking on them.

The controls here include four buttons, and a checkbox: The Tags Dialog

The Tags Dialog is used to manage the collection of defined tags. It consists of a list of the currently defined tags and four buttons. A tag can be selected from the tag list by clicking on it. You can also select multiple tags using the shift and command keys while you click. If you double click on a tag, you can select its name and edit it. Clicking the red close button closes the tag dialog.

The four buttons are as follows: The play mode frame

Below the music collection frame and its associated controls is a display showing information about the currently playing track: it shows the artist name, album name and track title, plus a real-time counter showing the current elapsed playing time on the track.

Below this display are a pair of radio buttons, two regular buttons, a couple of text fields, and the play control buttons:

On at the lower right is a set of conventional CD-player style control buttons: The Playlist Dialog

The Playlist Dialog is used to view and manipulate the playlist. It consists of the playlist itself and three buttons. A track in the display list can be selected by clicking on it. Multiple selection is supported in the usual way. You can close the dialog by clicking the red close button on the window.

The three buttons are as follows: The Patterns Dialog

Patterns are simply named boolean expressions of tag names and other patterns. They can be used for making more complicated selections of music. The Patterns Dialog lets you manipulate the collection of currently defined patterns.

The main body of the dialog window is a list of the names of all the currently defined patterns along with their definitions. A pattern can be selected by clicking on it. Double clicking on a pattern name or expression enables you to edit it.

Below this are three buttons: The Search Results Dialog

Various operations will bring up the Search Results Dialog. This shows you the set of items matching some tag or tag expression. You can select elements in the result set and add them to the playlist by clicking the "Add to Playlist" button. If no items are selected, the entire search result set will be added. You can also enter a new search expression and search again. Tag expressions

At several points above (setting the ambient mood, defining patterns, and using the Search Results Dialog), reference was made to tag expressions. These are boolean expressions which are used to match tracks to particular combinations of tag settings. The syntax of tag expressions is simple and primitive:

expr & term
expr | term


! term
( expr )

A bit more explanation:


An alphanumeric symbol should be the name of either a tag or a pattern. If it is a tag, it evaluates to true or false for a particular track depending on whether or not the named tag is attached to the track or its enclosing album or artist. If it is a pattern, then it evaluates to true or false for a particular track according to whether or not the pattern's associated expression evaluates to true or false for that track.

&, |, and !:

The boolean operator symbols &, |, and ! correspond to AND, OR and NOT respectively. If you don't know what this means, you shouldn't be using this feature.

Thus, for example, I have defined the pattern ok to be:

listenable | chip_fave | one_good_song

which identifies something I'm generally willing to listen to: either something that I've marked as sort of blandly normal (my listenable tag), or something marked as one of my favorites (my chip_fave tag), or the all too common case of the one good song on an album that otherwise sucks (which I mark with the one_good_song tag). Given this, I then defined a pattern ok_pop to be:

ok & !classical

which is all the stuff that matches the first pattern minus all the stuff marked as classical music.

5.4.3 Other modes

Ambient also has a text mode (command line) interface and a batch mode for processing its metadata file. Consult the Linux documentation if you really want to know about these.

6. Bugs & Todo

This thing really ought to use iTunes' metadata and music files instead of continuing to mess around with this silly CDDB stuff.

There should be a way to save and load playlists separate from the rest of the database.

Non-mouse operation of the GUI could be friendlier.

Arguably it would be better to actually use some kind of random-access database instead of rewriting everything on program exit. Life is full of trade-offs.

The mapping to .mp3 filenames could be more tolerant of different conventions for handling letter case and non-alphabetic characters. (Properly integrating with iTunes would take care of this.)

It would be nice to be able to edit the names of things from inside the GUI, rather than having to manually edit the .amb file or one of the CDDB cache files.

There should be a way for the GUI to link non-consecutive tracks. The text mode interface and the underlying player mechanism supports this but there are currently no GUI controls to make use of this feature. (On the other hand, it's not at all clear that this would be a terribly useful feature. YMMV)

Chip Morningstar (