The Standard Mp3 Database Project Documentation

Tom von Schwerdtner


tvon@etria.org

Revision History
Revision 0.012001-08-01Revised by: TGvS
Initial release.

This document is copyrighted (c) 2001 Tom von Schwerdtner and is distributed under the GNU Free Documentation License, stated below.

No liability for the contents of this document can be accepted. Use the concepts, examples and other content at your own risk. As this is a new edition of this document, there may be errors and inaccuracies, that may of course be damaging to your system. Proceed with caution, and although this is highly unlikely, the author(s) do not take any responsibility for that.

All copyrights are held by their respective owners, unless specifically noted otherwise. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark.

Naming of particular products or brands should not be seen as endorsements.

You are strongly recommended to take a backup of your system before major installation and backups at regular intervals.


Table of Contents
Forword
1. Introduction
2. The SMDP Database
2.1. Database Introduction
2.2. The Design of the SMDP Database
2.2.1. Database Structure
2.2.2. The Feature Tables
2.3. Database Specific Variations
3. The SMDP API
3.1. API Introduction
3.2. The Design of the SMDP API
3.3. Using the C API
3.4. Using the C++ API
3.5. Using the PHP API
3.6. Using the Perl API
A. Installing the SMDP
B. ID3v2.4 Frame Identifier Translations
C. Correlation Identifiers

Forword

A few years ago I went to one of those "Computer Expo and Sale" things that you always hear about on TV (the ones with the monster truck esque "sunday Sunday SUNDAY!" announcer that really speaks volumes aobut what the advertising people think of the target audience). I had never been to one of these shows and my only reason for going this time was to pick up a very large hard drive for a very small amount of money.

After a few hours of very careful comparison shopping, I settled my eyes on a 20 gig drive priced at a modest $150 or so (roughly the exact same price I would have payed for it anywhere else). The size of the drive was adequate for my purposes, since all I wanted to do was to pack it full of mp3's for my new "home-stereo" linux box I had just setup, and you can fit somewhere around 10,000 mp3's on a 20 gig drive without any problems, so, I was fairly pleased with myself.

At any rate, I took the drive home and quickly began ripping every sigle CD I owned onto it, and for a month or two it served me well as a fairly large repository of mp3's. Then, one sad day while I was trying out some "experimental" software (namely the BeOS demo for Linux), the entire drive was hopelessly corrupted beyond the reach of fsck or any other diagnostic software I could get my hands on. Needless to say, I was not happy. I ranted and raved for a while. I posted to newsgroups and mailing lists trying to find wasy to blame anyone but myself for using software that was very clearly labeled "alpha" and "100% totally and completely unsupported, use at your own risk". And then, I just sat there, and after a few minutes, I went on with my life and totally forgot about the drive.

About a year passed, maybe more, maybe less, and one faithful day a few months ago I randomly ran "fsck /dev/hdc" for kicks, and becuase I had upgraded things quite a few times since I had last tried anything on the drive. Well, to my total shock, fsck started running normally on the drive and, where previously it had very slowly spat out "I/O ERROR", it quickly spat out less serious but still not-kosher errors aobut inodes and last-mod times, and after about 20 minutes of checking, it finished up and I was able to mount the drive. So, once again I had access to my beloved mp3 collection.

Since I suddenly had a reasonable collection of mp3's again, I really wanted a good way to organize and make use of them. I searched around and came to the conclusion that one of the SQL based mp3 players was the best solution. I downloaded a few of these apps and after trying them out I became somewhat irritated at the amount of effort it took to setup a database, index it and load it up into an app just to find out that I really didnt like the app all that much of that it lacked one or two features that I really wanted. Don't get me wrong, the developers of these applications had some produced some really good players, but dealing with the database backend was a bit of a burden. So, my little brain started to churn out some smoke and I decided that it would be very cool if there was some sort of standard database for storing mp3's that all these apps used....FIXME

At any rate, the SMDP wont change the world, in fact, most people will never even know it exists, but it has so far been serving to "scratch an itch" as well as to provide some social enterntainment for a small handful of coders around the world. So, I hope you like it.

- Tom


Chapter 1. Introduction

The Standard Mp3 Database Project (SMDP) aims to make mp3 management easier for both the deveoper and the end-user. This document servers to assist developers in taking full advantage of the SMDP database and API, while cluing in the users as to the extent of the possabilities --FIXME--


Chapter 2. The SMDP Database

2.1. Database Introduction

In this section we will discuss some of the the ideas and reasoning that went into the design of the SMDP database. We will also discuss the varios diffrences you will encounter when using diffrent RDBMS's with the SMDP.

This section is not meant to be a tutorial or HOWTO on using databases, as some initial knowledge is required to understand the concepts discussed.


2.2. The Design of the SMDP Database

The SMDP database is designed to allow for a very dynamic set of information relating to mp3 and ogg files. The basic structure covers the usual entities in a traditional relational model. This is then complemented by a set of tables essentially composing a directory-like storage structure, geared toward both specific attribute classes as well as a completely "free" relations table - ie where the type of the objects are specified on both sides of the relation.

This provides, in addition to the usual information such as artist name, song title, album name and so on, for space to define unique information as well as to establish relationships betewwen any two objects in the database.

Anyways, enough of the hot air...read on for more information.


2.2.1. Database Structure

There are two schemas available for the SMDP database, the core database and the core database with the optional extension.

The schemas break down as follows:

  • core schema

    • artist information

    • album information

    • artist information

    • file information

    • media (filesystem) information

    • Id3 tag/Ogg comment information

    • audio class information (genres)

    • correlations (object relationships)

  • optional schema

The core schema is meant to be used in situations where the user does not want or care for the extra information available in the optional schema.


2.2.1.1. The Core Schema

The core schema holds all the information that is considered essential to a functional mp3/ogg database. This basically means, all information that can be represented with Id3 tags or Ogg comments minus lyrics information and binary data. [note: binary data can still be refrenced with the core schema, however the actual data will remain in the respective mp3 or ogg file]

Figure 2-1. Core ERD

ERD of the core SMDP Database


2.2.1.2. The Optional Schema

The optional schema adds a few more features to the database that allow for a slightly more full-featured set of data. With the optional schema you can store MusicBrainz and FreeDB data, as well as Lyrics information and binary data.

Figure 2-2. Optional ERD

ERD of the optional SMDP Database


2.2.2. The Feature Tables

For each of the main objects in the database, there exists a companion 'feature' table. The 'feature' tables serves to further describe the records in the object table.

See Appendix B for information on translating Id3 tags and Ogg comments into SMDP records.


Chapter 3. The SMDP API

3.1. API Introduction

API Introduction goes here


3.2. The Design of the SMDP API

API Introduction goes here


3.3. Using the C API

API Introduction goes here


3.4. Using the C++ API

API Introduction goes here


3.5. Using the PHP API

API Introduction goes here


3.6. Using the Perl API

API Introduction goes here


Appendix A. Installing the SMDP

...


Appendix B. ID3v2.4 Frame Identifier Translations

Up-to-date ID3 Frame Identfiers can be found at the official id3 website.

Table B-1. ID3v2.4 -> SMDP Storage

Frame IdDescriptionLocation in SMDP
AENCAudio encryptionSMDP Table
APICAttached picture 
COMMComments 
COMRCommercial Frame 
ENCREncryption method registration 
EQUAEqualization 
ETCOEvent timing codes 
GEOBGeneral encapsulated object 
GRIDGroup identification registration 
IPLSInvolved people list 
LINKLinked information 
MCDIMusic CD identifier 
MLLTMPEG location lookup table 
OWNEOwnership frame 
PRIVPrivate frame 
PCNTPlay counter 
POPMPopularimeter 
POSSPosition synchronisation frame 
RBUFRecommended buffer size 
RVADRelative volume adjustment 
RVRBReverb 
SYLTSynchronized lyric/text 
SYTCSynchronized tempo codes 
TALBAlbum/Movie/Show title 
TBPMBPM (beats per minute) 
TCOMComposer 
TCONContent type 
TCOPCopyright message 
TDATDate 
TDLYPlaylist delay 
TENCEncoded by 
TEXTLyricist/Text writer 
TFLTFile type 
TIPLInvolved people list 
TIT1Content group description 
TIT2Title/songname/content description 
TIT3Subtitle/Description refinement 
TKEYInitial key 
TLANLanguage(s) 
TLENLength 
TMCLMusician credits list 
TMEDMedia type 
TMOOMood 
TOALOriginal album/movie/show title 
TOFNOriginal filename 
TOLYOriginal lyricist(s)/text writer(s) 
TOPEOriginal artist(s)/performer(s) 
TOWNFile owner/licensee 
TPE1Lead performer(s)/Soloist(s) 
TPE2Band/orchestra/accompaniment 
TPE3Conductor/performer refinement 
TPE4Interpreted, remixed, or otherwise modified by 
TPOSPart of set 
TPROProduced notice 
TPUBPublisher 
TRCKTrack number/Position in set 
TRSNInternet radio station name 
TRSOInternet radio station owner 
TSOAAlbum sort order 
TSOPPerformer sort order 
TSOTTitle sort order 
TSRCISRC (international standard recording code) 
TSSESoftware/Hardware and settings used for encoding 
TSSTSet subtitle 
TXXXUser defined text information frame 
UFIDUnique file identifier 
USERTerms of use 
USLTUnsynchronised lyric/text transcription 
WCOMCommercial information 
WCOPCopyright/Legal information 
WOAFOfficial audio file webpage 
WOAROfficial artist/performer webpage 
WOASOfficial audio source webpage 
WORSOfficial Internet radio station homepage 
WPAYPayment 
WPUBPublishers official webpage 
WXXXUser defined URL link frame 
Frame IdDescriptionLocation in SMDP


Appendix C. Correlation Identifiers

If you wish to add identifiers, please contact the SMDP developers first to prevent overlapping values.

Table C-1. Correlation Identifiers

BinaryDecimalRepresents
0000011Song
0000102Artist
0000113Album
0001004 
 5 
 6 
 7 
 8 
 9 
 10 
 11 
 12 
 13 
 14 
 15 
 16 
 17 
 18 
 19 
 20 
 21 
 22 
 23 
 24 
 25 
 26 
 27 
 28 
 29 
 30 
 31 
 32 
BinaryDecimalRepresents