Page History: MP3-CMS Public Wiki
Compare Page Revisions
Page Revision: 2009/10/16 10:42
Welcome to
MP3-CMS Wiki!
This documentation wiki has been established to allow the MP3-CMS community to share in the
installation documentation in order to provide new users the quickest, most reliable way to
get up to speed and use the CMS server as effectively as possible.
Introduction
 MP3-CMS Get Album Page |
Even in 2008 managing digital music libraries remains an enduring problem in a distributed environment. Most of us have PCs or PC appliances in just about every room in the house. Making sure all of these devices have access to the family's digital music library seems as simple as creating a file server. However as the features included in these standalone players increase, so do application footprints. Each application needs to expend time and cycles scanning the file server for music, updating its database, and then there's the problem of synchronization or having to make sure that all these applications have the newest music in their databases.
What is needed is a single interface, with common features that runs entirely from a Web server. It needs to be intelligent. Specifically it should allow consumers to create playlists, rate tracks, comment on albums, generate smart playlists based on criteria such as star ratings, genres, newest tracks, and most importantly it should remember which tracks have been played and how often. Based on such analysis the system should recommend music and this system should be self-contained with as little administration as possible. If the users add or delete music from the server, the system should update itself appropriately.
The MP3-CMS is server based music management system that addresses these traditional constraints. It provides a clean user interface for cataloging
and listening to your music from a web browser. The system is composed of 2 components: a web site and a scanner. The scanner application is embedded in the web site and runs concurrently. The scanner identifies the path it should scan from the site's configuration files and it runs in the background behind the scenes and watches the path for changes. As you go about your business adding new mp3s or deleting them, the scanner will automatically detect this activity and update the embedded Sqlite database accordingly.
In order to run the MP3-CMS, you need some mp3 files and a
Windows server running IIS & ASP.NET v2.0 w/AJAX.
Pre-requisites
Setup is pretty simple in the latest release v2.0.0.0; consisting of setting the path to your music, and setting permissions for the website to access both of these directories. However, there are some things that you'll want to do prior to installation to ensure that you get the best experience possible.
Folder Naming Conventions
For optimum performance I recommend that you use the following convention to establish your collection:
Folder:
<Genre>\<Artist>\<Album>\<*.mp3>For example: \\baileydc02\Music\Rock\A Perfect Circle\02 Thirteen Step (2003)\blue.mp3
At the very least please ensure that albums are contained in their own folder. This makes things much easier because the scanner queues up all the music files and album art in each folder and processes them in batch. The queuing is much more efficient when there is a logical folder structure in place.
Note: if you do not group albums by artists you will not be able to use the fan-art feature
ID3 Tags
Before you start the installation it's highly recommended that you do some pre-requisite work on your collection to ensure that your music files are properly tagged. It you choose to skip this step it's entirely possible that you will end up with a situation where you have the same artists or genres several times in different formats. For example, you could easily end up with a situation like this:
With AC/DC appearing as 4 different artists. The same holds true with albums and genres. You certainly don't want different genres for Pop and pop or Rap and Hip-Hop, or Rock and Alt.Rock.
ID3 Tags are metadata containers embedded in mp3 music files that describe the file. This is how applications determine what the song title is, the artist, album, etc. If you have not ever modified your ID3Tags then chances are that many of them are incorrect. If you want the full MP3-CMS experience then you'll want to follow these ID3Tag Guidelines:
- Validate that all Artists match correctly. (AC/DC is not the same as Ac/dc)
- Decide on a limited number of genres and place all tracks in these genres
- If a CD has more than one artist then set the Band tag to Various Artists
- Separate large Albums into smaller ones. Do let any CD contain more than 25 tracks
At the minimum every track in the collection must have these tags:
I recommend
MP3Tag to manage ID3Tags. It's free and excellent, allowing for batch tagging and tagging based on filename (a real time-saver). In addition it runs under WINE in linux which is a huge plus. Please do not continue the installation without checking your collection for proper tags.
Mp3Tag.de
 Mp3Tag.de User Interface |
Mp3Tag.de is an amazing program for fixing large libraries in batch. I'm going to walk you through a scenario where I will demonstrate how to quickly repair ID3Tags in an album. In this scenario I have a CD called
The Blackest Album - An Industrial Tribute to Metallica. This CD contains a mix of artists so it is said to contain
Various Artists. The album has several artists but each track only has a single artist.
To begin we load the folder which contains this CD into mp3tag.de and take a look at the existing ID3Tags, where we find several problems:
 Incorrect tags are embedded in these files |
For some strange reason, the tagging software has embedded both the artist name and the song title into the
Title ID3Tag. We are going to click in a Title column row and delete out the artist from the column so it only displays the actual song title.
 Removing the artist name from the title tag in the final album track |
All these tracks contain an
Artist ID3Tag set to
Various. There is no such group named Various and as such the Artist tag should ONLY be the artist who sings that specific track. If an album contains Various Artists, then that information is stored in the
Band tag, discussed later. We are going to click in an Artist column row and replace Various with the actual artist for that song.
 Inputing the correct Artist for each track |
Obviously, you might not want to do this one at a time and you can automate this process. If you highlight all the tracks and right click; select the Convert >FileName to Tag option a dialog box is displayed.
 Using the Convert batch options |
 Using a format pattern to set tags based on filename |
Its a little tricky to get used to but it works really well. A file was named: 06 Various - Razed In Black Damage Inc.mp3. By looking at this filename it appears clear that the track number is 6, the band (AlbumArtist) is Various, the artist is Razed in Black and the title is Damage Inc. So we use the format:
%Track% %Band% - %Artist% %Title% to copy these values from the file name and insert them into the ID3Tags.
NOTE: Various is not a valid entry for the Band tag but it's ok, we're going to change that to Various Artists in the next step.
By default mp3tag doesn't display the
band tag (otherwise known in Windows Media Player as
AlbumArtist). The band tag is used to store the artist for an album (as opposed to the Artist tag which is used to store the artist for the individual track). We need this tag to be set properly for albums containing various artists.
To modify the order of the columns or, in our case, to add additional tags into the program display we right click on a column and select the customize columns option:
 Re-ordering columns or adding new one |
In the Columns dialog box, click the new button and enter the information below:
 Columns dialog box |
Ok, now that the Artist, Track, and Title tags have been corrected by using their file names as a rename template, we're going to tidy up the rest of the tags at the same time. We highlight all the tracks, right click, select the Extended Tags option:
 Modifying all the tags together |
In the dialog box that appears, we change the Band value to
Various Artists and we change the Genre from Rock to Metal. We also add the cover art.
 Editing ID3Tags in batch for all selected tracks |
As a final cleanup measure, we want to rename all the files so they match the new, and correct, ID3Tags. From the right-click context menu with all items selected, we select the Convert > Tag to Filename option. And use the format string %track% %artist% - %title%, which renames all of our files based on the tag data.
 Renaming all files based on ID3Tag data |
Below you can see our shiny new Album with all the correct ID3Tags, cover art, and file names.
 ID3Tags are all set correctly |
A final note here, this is a very unusual circumstance. Most of the time its just a matter of making sure the tags are correct and fixing them when they aren't.
Managing Singles
As you're fixing your ID3Tags a unique problem arises when dealing with single tracks. Single tracks are songs that you may have that either do not have a full album associated to it or you only have only a few songs from an album. If you have a lot of these kinds of files you may not want the mp3-cms to treat 1 or 2 stray songs as an entire album. The solution to this is to create
logical albums that don't exist in the real world but group orphaned tracks together.
I am not a big fan of the
Rap music genre so most of the rap songs I have are singles. As you can see below, I created a folder in each genre folder called Singles. Inside the Rap\singles folder I create a folder called
Hot Rap Tracks, which, of course, is not a real album. Hot Rap Tracks is the name of my
logical album for storing orphaned rap songs. I have nearly 100 single Rap songs so I create folders in
Hot Rap Tracks, 01, 02, 03, and 04, placing 25 songs into each folder.
 Grouping orphaned tracks together in logical albums |
After I move my tracks into the Rap\Singles\Hot Rap Tracks\[01-04] folders, I load these folders into
Mp3tag.de. I highlight all the tracks in the 01 folder and change the
Album tag to
Hot Rap Singles CD1. I do the same for all the rest of the numbered folders until all my orphans have a CD.
 Creating logical albums to group orphans |
I also like to clear out the Track id3 tag so the web site orders the CD in the CMS by Artist name.
You may be wondering why we don't just put all the single tracks in one logical album called Hot Rap Tracks? You can certainly do that but it will negatively impact the performance of the CMS because album playlists are generated dynamically by the application. Obviously if a CD has 100+ tracks in it, the application takes much longer to fetch and order the from the database, generate the valid XSPF playlist, and send the request to the client.
Album Art
CD Cover art is critical to user satisfaction and we highly recommend that you spend some time before the installation obtaining Album art for each album in your collection. You have 2 options when it comes to art:
- Name the cover image folder.jpg and place it in the root of the album's folder
- Use a ID3Tag program, such as Mp3Tag.de to embed the cover art into each file in the collection
Either of these 2 options will result in your CD cover art being displayed properly. There are a lot of places to locate cover art but the best is by far,
SlothRadio. If no cover art is found in the album's folder or embedded in the file then the scanner will display the no_cover.gif file from the images directory in it's place.
If the scanner has already run and you did not have the cover at that time, you can manually add the cover art into the system by renaming the cover image
.jpg and copying it to your App_Data\CoverArt directory on the server. You can retrieve the Id of the album by opening it's page in MP3-CMS and looking at the Url. For example: http://baileyweb01/music/forms/getAlbum.aspx?albumid=8388618.
Or you can manually add cover art in the AlbumDetails.aspx page (only available to Administrators and Managers).
Fan Art
A new feature in this release is the inclusion of fan art. Fan art are image files like cover inserts, artist posters, and wallpapers for artists. Fan art isn't cached and is determined at run time. When a user opens an artist's page in the web site there is a side bar with a link called FanArt. If you click on this link a partial postback request is executed which searches the folder above the album for JPG files. These files will be displayed in the side bar.
 Artist Page with Fan Art |
Installation
Note: These instructions assume you are using a 32-bit server. Refer to
this forum post for changes needed to install on 64-bit servers
Installation Wizard
NOTE: The installation wizard is still experimental and potentially volatile. Reports errors to the
forums.
Review Server Requirements
Please validate this configuration on your server before executing the setup wizard:
Run the Setup Wizard
- Unzip the package into a folder called music in your web site directory (e.g. c:\Inetpub\wwwroot\music)
- Run the setup script (install.hta)
- Use the Browse button to locate or enter the full path to the root music folder
- Click the Install button
Security Considerations
The installer is written in JavaScript and can be edited in notepad. The installer will create a service account in which the website will run as.
If your music folder is on a separate machine than the web site (this is the recommended architecture), but you are not on a domain then you need to edit the JavaScript file's (install.hta) variables _userName and _password to reflect an account on the remote music server that has permission to read & write to the root music share before you run the installer.
If you are on a domain and your music folder is on a remote file share (recommended) then you need to edit the JavaScript variables _username and _password to reflect a domain account with permission to read & write to the remote share (e.g. \). The script will fail to create the account since it already exists but the rest of the setup should complete successfully.
Manual Installation
Configure ASP.NET Application
Unzip the website you downloaded from nealosis.com or sourceforge.net and copy it to your server. Usually this is c:\Inetpub\wwwroot\music. You'll need to create the music folder of course.
Set Music Path
The system configuration files are located in the path ~/config/my_settings/. You only need to edit the AppSettings.xml file:
1. AppSettings.xml: Edit the ScanPath key. Set it to your root music path:
<appSettings>
<!–– scanPath
The physical path of the root of the MP3 library to scan.
––>
<add key="scanPath" value="\\baileyfs01\Music"/>
<!–– disableScanner
Whether or not scanning should be disabled.
––>
<add key="disableScanner" value="false"/>
<!–– default adminPassword
The default Administrator account's password
––>
<add key="adminPassword" value="password"/>
<!–– bannerMessage
The text displayed in the header of the site.
––>
<add key="bannerMessage" value="MP3-CMS Server"/>
</appSettings>
Edit Folder Security
You need to grant the application rights to read your collection and edit the database. Grant the NETWORK_SERVICE account Read & Execute, Write, and Modify permissions to the ~/App_Data folder. You can access the permissions (ACL) by right clicking on the App_Data folder and selecting the Security tab.
 Database Folder Properties Sheet |
 Security Settings For App_Data |
Finally, grant the NETWORK_SERVICE account Read & Execute and List permissions to your ScanPath folder (so the application can scan your music). Follow the same steps above for the folder which has all your music.
Note: for increased security you could also use a domain service account. In order to do this, grant the service account permissions to the App_Data Folder and the directory with your music. When you setup your web service in the next step, you need to change the web site's Application Pool Identity property to the service account. This is not necessary for most users.
Configure IIS 6.0 Server
All steps are assumed for Internet Information Server (IIS) v6.0 unless otherwise noted.
Please be sure you have installed the ASP.NET AJAX 1.0 Extensions before proceeding.
Virtual Directory Wizard
- Open the Internet Services Manager applet by executing the command in the run menu:
%SystemRoot%\system32\inetsrv\iis.msc
- Navigate to Default Web Site. Right click on this node and select New > Virtual Directory. Follow the wizard through the steps and enter the following values when prompted (be sure the path is set to the location you copied the website to):
Alias: Music
Path: c:\inetpub\wwwroot\music
Access Permissions: Read, Run Scripts, Execute, Write
- Right click on the newly created virtual directory and select Properties. In the properties sheet open the documents tab. If there is no file called default.aspx in the list of default documents then add default.aspx in the list.
- In the ASP.NET tab ensure that the version selected is 2.0.50727 (or higher).
- Check that the IIS virtual directory is configured as an application (this setting is usually set by default)
 Ensure the virtual directory is configured as an application |
Configure the Application Pool
- With the Internet Service Manager applet open, expand the Application Pools folder. Right click the DefaultAppPool item and select properties. In the Performance tab there is an Idle Timeout section. Uncheck the only option in this section: disable timeouts. This step will allow the scanner to run all the time and not timeout.
- Click the Identity tab. You should see NETWORK_SERVICE as the pre-defined Application Pool Identity.
NOTE: if you want added security and would like the website to run under the context of a special domain service account you need to add that account into the pre-defined Application Pool Identity section of the Application Pool's property sheet. Please consider that regular accounts are different than service accounts and in order for an account to become a service account it needs to be a member of the security group, IIS_WPG which will grant the group policy right Log on as a Service.
Internet Information Services 7
If you want to run mp3-cms (and all it's Ajax controls) in IIS 7, then you have to configure the managed pipeline mode in the AppPool to run in Classic Mode. Here is a link that demonstrates how to do this.
Testing the Installation
If you've properly set everything up then you can now open your web browser and connect to the MP3-CMS. http://YourServer/music/. You should see the login screen:
 The login screen for the CMS |
You can create an account but since administrators have to activate new accounts, its best to log in with the administrator account and use the management tools to create your accounts.
Default Admin Account
User Name: admin
Password: password
After you log in you may want to check the log file in your App_Data folder to ensure that your music is scanning ok and then navigate to the management section in the Admin menu to create new accounts.
Configure Cassini Web Server
Coming Soon! It's been tested and works great!
Configure XSP Apache Mono Web Server
Coming Soon! Tested only experimentally :(
System Administration
Adding Music
Because of the size of mp3 files and the amount of them in most collections, its not feasible to allow users to upload them through a web interface. Rather it's much more efficient to create a windows network share on either the web server or file server to host the music collection. Another advantage to this is the added security available with shares. In most of our implementations we create a share with 2 folders:
- Music: The root directory of the collection.
- Upload: The directory to upload new mp3s.
The Mp3Scanner is set to watch the Music directory and only administrators & music managers have write access to the share. All users have access to the Upload directory. Using this strategy, approved administrators have the opportunity to load all the new files into Mp3Tag.de and ensure the ID3Tags for each track is set correctly and do any cleanup before copying them to the appropriate directory (which the scanner picks up and adds into the system automatically when they are copied into anywhere in the Music directory).
Adding Fan Art
Fan art are images like album inserts, wallpaper, and posters for an artist. It is not cached or thumbnailed; rather it's determined at run time by the application. See This previous section on how to display fan art in an artist page.
To add fan art just copy the JPG image files into the artist's folder (the folder above the albums). For example I might have \\baileyweb01\Music\Rock\Anthrax\Persistence of Time. The fan art needs to be located in \\baileyweb01\Music\Rock\Anthrax.
Adding Users
Users can create their own accounts at the login page but by default but these accounts cannot be used until an administrator activates the account. To activate accounts or create new accounts, log in as an administrator and navigate to the Admin page. The management options are listed and clicking on each of them expands the category, see below:
 Adding a new user to the cms |
Enter the username, password, and select the role of the user. In order for an account to be considered "Active", they must be a member of users.
Account Permissions
Remove Admin Approval for New Accounts
As stated above, by default users can create accounts but cannot log in until an administrator activate the account (by adding the account to the users group). You can modify this behavior by editing the Web.config file in the root of the web site. Below you will see the default authorization key settings:
<authorization>
<!–– Deny all users except those who are a member of a valid role. ––>
<allow roles="Administrators"/>
<allow roles="Managers"/>
<allow roles="Users"/>
<deny users="*"/>
<!–– Only deny anonymous users.
<deny users="?"/>
––>
</authorization>
If you want all users to be able to create accounts and log-in without requiring administrator approval then change the above to:
<authorization>
<deny users="?"/>
</authorization>
Edit User Permissions
The CMS comes with 3 roles, each of which provide their own unique set of permissions. The roles are:
- Administrators
- Managers
- Users
Administrators have full control of the cms, Managers (or Music Managers) can perform all tasks except those involving membership and system settings, and users can perform all tasks relating to their profile but cannot edit global data like artist biographies or album reviews.
To edit user rights (role membership) log in as an administrator and navigate to the Admin section. Click the Manage Permissions link to expand the control.
From the User Name drop down, select a user and then select an action to take (Assign Role or Remove Role Assignment). When you select "Add", the roles the user is currently NOT assigned to appear in the list box. When you select "Remove", the roles the user IS currently assigned are displayed. See example below.
 Assigning user roles |
Web Site Management
The web site is configured by ASP.NET configuration files that can be edited to alter the behavior of the application. Be very careful when editing these files. A mistake could corrupt the installation and any change made will recycle the IIS Worker Process and all active users will loose their session.
AppSettings.xml
<appSettings>
<!–– scanPath
The physical path of the root of the MP3 library to scan.
––>
<add key="scanPath" value="\\baileyfs01\Music\Rock"/>
<!–– disableScanner
Whether or not scanning should be disabled.
––>
<add key="disableScanner" value="false"/>
<!–– default adminPassword
The default Administrator account's password.
––>
<add key="adminPassword" value="password"/>
<!–– bannerMessage
The text displayed in the header of the site.
––>
<add key="bannerMessage" value="MP3–CMS Server"/>
</appSettings>
- scanPath - defines the location of the music files.
- disableScanner - Turns the scanner off. If you want to prevent new music from being added to the system, disable the scanner.
- adminPassword - Defines the default password for the admin account. This can only be set on new databases.
- bannerMessage - The text displayed in the header of the web site.
MembershipProvider.xml
<membership defaultProvider="Mp3CmsMembershipProvider">
<providers>
<clear/>
<add name="Mp3CmsMembershipProvider" type="Mp3CmsMembershipProvider, App_Code"
enablePasswordReset="true"
enablePasswordRetrieval="true"
minRequiredNonAlphanumericCharacters="0" minRequiredPasswordLength="3" passwordFormat="Encrypted"
maxInvalidPasswordAttempts="5" passwordAttemptWindow="5"
requiresQuestionAndAnswer="true"
requiresUniqueEmail="false"
passwordSaltSize="16"
/>
</providers>
</membership>
These settings define the behavior of the membership provider. For a full list of options check this MSDN article. A word of caution though. not all these settings have been tested.
NHibernate.config
<property name="connection.connection_string">Data Source=|DataDirectory|music.db3;Page Size=4096;Synchronous=Off</property >
<property name="dialect">NHibernate.Dialect.SQLiteDialect</property>
<property name="connection.driver_class">NHibernate.Driver.SQLite20Driver</property>
<property name="query.substitutions">true=1, false=0</property>
<property name="connection.provider">NHibernate.Connection.DriverConnectionProvider</property>
<property name="connection.isolation">ReadCommitted</property>
<property name="show_sql">false</property>
These settings should be left alone. This file has a lot of comments with details of other database engines we have tested (Firebird, MS-SQL, etc). If you'd like the scanner to create a database in a specific location you can edit the connection string and enter a fully qualified path to a db3 database.
RoleProvider.config
<roleManager enabled="true" defaultProvider="Mp3CmsRoleProvider"
cacheRolesInCookie="true"
cookieName=".ASPROLES"
cookieTimeout="30"
cookiePath="/"
cookieRequireSSL="false"
cookieSlidingExpiration="true"
cookieProtection="All">
<providers>
<clear/>
<add name="Mp3CmsRoleProvider" type="Mp3CmsRoleProvider, App_Code"/>
</providers>
</roleManager>
These settings define the behavior of the role management provider. For a full list of options check this MSDN article. A word of caution though. not all these settings have been tested.
Web.config
This is the core configuration for the website. There are some interesting settings that you can customize but generally speaking proceed with caution when editing these values.
One of the key elements is the authorization key which allows you to enable or disable whether or not new user accounts must be activated. See this earlier section for instructions on doing this.
You can also edit the compilation key, to turn off debugging. If you plan on running this on the internet then you should set the value to false so your web server doesn't expose sensitive server information if the application experiences an error.
<compilation debug="true" strict="false" explicit="true">
Scanner Management
In the earliest releases of mp3-cms, the scanner was a separate console application and later it was an NT Service component. With the last release we moved it into the base engine of the website in order to simplify things and consolidate logic. The scanner creates a log file in the web site's App_Data directory called log.txt where all of it's actions are accounted for. The scanner runs each time the web site is started or when an event is triggered by the file system.
Scan Workflow
The scanner works in an ordered fashion based off a queuing system. When the scanner kicks off it navigates each directory and sub-directory of the scan path and checks each file to see if it's in the database based on a concatenation of the file's directory and name. If the file is not in the database then it is queued up for processing. When all the files in the folder are queued, the QueueProcessor engine processes those files:
- Extracts ID3Tag header metadata
- Publishes file and id3 info in the database
- Checks for folder.jpg and if not found then it extracts the header frame of the file for art
- Generates a thumbnail for the art
- Copies the thumbnail to the coverArt folder
- Determines orphaned Artists, Albums, Genres, and Years
- Cleans up orphans out of the database
Wash, rinse, repeat for each folder & sub folders under your scan path directory.
You can watch this orderly process in process by viewing you log.txt file in the App_Data directory.
Triggers
The Mp3Scanner component uses a FileSystemWatcher entity to monitor the scan path set in the /config/my_settings/AppSettings.xml file. Whenever a file is added or deleted from the directory the scanner is triggered to take action on the files; either by scrubbing the records from the database or by adding them into it.
Due to some time comparison issues we experienced in mp3-cms v1.5.x, we no longer compare the file's modified date in the database to the file's modified date to do updates. If you make a change to some tracks, like editing ID3Tags, it's recommended that you use a batch process to rename the files, which will trigger a DELETE > ADD workflow in the scanner.
Warning: by renaming files, you will loose saved song lyrics, track ratings, and any other user metadata regarding these tracks.
If the scanner cannot read the header information in a file, it will re-queue it and continuously try every few seconds to read it. If after 5 minutes the scanner still cannot get the meta data header info, it will expire and give up on the track.
Forcing a scan
If for some reason the directory containing the music files was unavailable at the time of a critical change and you want to initiate a scan you can restart the IIS/ASPNET stack by running the following command in the server's command prompt:
c:\Windows\System32>iisreset
This will bring everything down and back up again in the correct sequence. The next connection to the mp3-cms will initialize the scanner and start a new scan.
Thumbnail generation
As part of the scanning process, the scanner will attempt to generate 200px X 200px thumbnail images of CD cover art. The scanner will first look in each track's folder for a file called folder.jpg and if it's found then the scanner will generate a thumbnail and move it to the ~/AppData directory on the web server. If no folder.jpg file is found, then the scanner will attempt to extract a cover directly out of the track's ID3Tag metadata header. Thumbnails are always named .jpg. You can determine an album's Id value by looking at the url string when you open the album's page in the website or by doing a query against the database directly.
SQLite Management
The database we've selected for the last several releases is SQLite, mostly because its outstanding performance and flat file architecture. You shouldn't ever need to do anything with it but if you want to poke around, feel free. I use a program called SQLite Administrator to interact with it in a graphical interface. You can see all the database tables, the indexes, and even run queries against you database if you so choose.
 Running a Query for Most Played Tracks |
You can see from the query I have run that I am asking the database to return a results set that shows me the most played tracks for all users in the database.
Creating a new database
If you find that your ID3Tags are all wrong and you want to fix them with Mp3Tag.de and then rescan everything all over again then all you need to do is delete the file music.db3! The next time you connect to the website a new database will be generated for you!
Warning: If you have mp3-cms generate a new database for you the scanner will not start right away. It's best to review the log and when there has been no activity for a few minutes after the new database is generated, restart iis with the iisreset command and the next web request will kick off the scanner.
Upgrading to Mp3-Cms v2.0
Luckily, the database design we developed is just that good that we didn't need to make any changes to it! When you install the site, copy your old music.db3 file from v1.5.x into the new AppData folder and all your play lists, reviews, star ratings, etc will be preserved!
Logging Engine
The application log file (~/App_Data/log.txt) is your window into the processing of the application. Every action the scanner takes is accountable to the log file.
Log4Net
The log engine (log4Net) that ships with mp3-cms is set to debug mode, meaning that your log files are going to be astronomically huge in size! Once you're satisfied that the scanner is working correctly and everything is ok, you can edit the log4net.config file (in the root of the install) and turn off debug logging.
<log4net debug="false">
<appender name="trace" type="log4net.Appender.TraceAppender, log4net">
<layout type="log4net.Layout.PatternLayout,log4net">
<param name="ConversionPattern" value="%d [%t] %–5p [%x] <%X{auth}> – %m%n"/>
</layout>
</appender>
<appender name="rollingFile" type="log4net.Appender.RollingFileAppender">
<file value="App_Data\log.txt" />
<appendToFile value="true" />
<rollingStyle value="Size" />
<maxSizeRollBackups value="20" />
<maximumFileSize value="10MB" />
<staticLogFileName value="true" />
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%date [%thread] %–5level %logger [%property{NDC}] – %message%newline" />
</layout>
</appender>
<root>
<priority value="WARN"/>
<appender–ref ref="trace"/>
<appender–ref ref="rollingFile"/>
</root>
<logger name="baileysoft.mp3">
<priority value="DEBUG" />
</logger>
</log4net>
You can change the priority value from "DEBUG" to "INFO" to turn off verbose debug logging. Here are some sample configurations you can review for more detail
Interpreting Messages
The log is pretty straight forward. It lets you know when it starts and what it's doing:
2009-06-25 14:21:47,349 [4] INFO baileysoft.mp3.Mp3Scanner [(null)] - Scanner started.
2009-06-25 14:21:47,708 [8] INFO baileysoft.mp3.Mp3Scanner [(null)] - Building list of file records that are no longer valid.
2009-06-25 14:21:47,926 [8] INFO baileysoft.mp3.Mp3Scanner [(null)] - Scanning for new files since last execution.
2009-06-25 14:21:47,926 [8] DEBUG baileysoft.mp3.Mp3Scanner [(null)] - Scanning folder \\baileyfs01\Music\Rock for new files.
2009-06-25 14:21:47,942 [8] DEBUG baileysoft.mp3.Mp3Scanner [(null)] - Scanning folder \\baileyfs01\Music\Rock\311 for new files.
2009-06-25 14:21:47,957 [8] DEBUG baileysoft.mp3.Mp3Scanner [(null)] - Scanning folder \\baileyfs01\Music\Rock\311\311 (1995) for new files.
2009-06-25 14:21:47,957 [8] DEBUG baileysoft.mp3.Mp3Scanner [(null)] - Checking file '\\baileyfs01\Music\Rock\311\311 (1995)\01 311 - Down.mp3'
Here are some more typical messages:
2009-06-25 14:22:50,186 [8] DEBUG baileysoft.mp3.Mp3Scanner [(null)] - Logically deleting Genres that are no longer in use.
2009-06-25 14:22:50,186 [8] DEBUG baileysoft.mp3.Mp3Scanner [(null)] - Logically deleting Years that are no longer in use.
2009-06-25 14:22:50,186 [8] DEBUG baileysoft.mp3.Mp3Scanner [(null)] - Logically deleting Artists that are no longer in use.
2009-06-25 14:22:50,186 [8] DEBUG baileysoft.mp3.Mp3Scanner [(null)] - Logically deleting Albums that are no longer in use.
2009-06-25 14:22:50,201 [8] DEBUG baileysoft.mp3.Mp3Scanner [(null)] - Caching cover art for album 131126 from folder.jpg.
2009-06-25 14:22:50,264 [8] DEBUG baileysoft.mp3.Mp3Scanner [(null)] - Updating statistics.
Use these log messages in the forum when you need support.
The log will display some errors when the database is being built but that's normal due to it's structure.
Troubleshooting
Users Guide
Finding Music
Of course you can browse the collection by clicking the Artists, Albums, or Genres link in the page banner to go to the browse collection pages.
If you'd like to search the database for an artist, album or song you can do so by clicking the Search link the the header banner. From the dropdown, select what type of search you'd like to do (song title, artist, or album) and enter your search criteria.
Note: you can wild card searches with the % character. For example the search love% would return all matches that start with the word love but the search %love returns any match that ends with the word love.
Track & Album Ratings
Just about everywhere you see a track listing or an album there is a series of 5 stars next to it. You can mouse over the stars and rate the song or album from 1 (horrible) to 5 (totally awesome) stars. These ratings only apply to your profile. By rating a track or album you will not interfere with anyone else's ratings. As you rate tracks an automatic star rating play list is being generated on your behalf. You can listen to this play list from the playlists page.
Recommending Tracks
As you're navigating the system you will often see a table like this, denoting the tracks in an album (or tracks from an artist).
 An Album's Tracks Grid |
The green check marks next to a track indicates a Recommended Song. Recommended songs are any songs in the mp3-cms which are rated by any user with a 4 or 5 star rating. A 4 star rating is equal to I Really Like and a 5 star rating is equal to I Absolutely Love. If a user really likes or absolutely loves a track, then the track is flagged as a recommended track for all users in the system.
Album Comments
At the bottom of every album page there is a box where users can leave comments about the album. Users are only allowed 1 comment per album (though you can change your comment as often as you want).
Viewing Fan Art
At the artist page there is a control called FanArt in the right panel of the page. Clicking on the link will initiate a Ajax postback to fetch any fan art in the system. Refer to this section for more details.
Viewing AudioScrobbler Data
On the left hand side of the artist page you'll notice the Audio-Scrobbler logo. Below it are the feeds available. clicking on either of the links will fetch the stream data from Last.fm.
 Viewing an AudioScrobbler Internet Data Stream |
Managing Playlists
Creating & Deleting Playlists
Before you can add songs into a play list, you need to create a play list to put songs into. Of course, you could just give songs a star rating and let mp3-cms create an automatic play list for you based on your star ratings. However there is a very good reason to create play lists. Play lists let you partition music into sub-units. You might rate a Rap song 5 stars and you might also rate a Metal song 5 stars but that doesn't necessarily mean that you want to listen to these songs back to back in the same play list.
One of the best examples is the creation of a Christmas or a Memorial Day Cookout play list which only contains tracks that are either holiday related or appropriate for company.
To create a new playlist, navigate to the play list page by clicking the Playlist link in the header of the page.
 Creating a Memorial Day Playlist |
When you click 'Create', the new play list will appear in the listen and edit drop down lists. If you wish to destroy the playlist then click the 'Delete' button to scrub it from the database forever.
Adding Tracks to Playlists
After you have created a play list, you can add songs into it from any track listing in the site:
- GetAlbum Page
- GetArtist Page
- PlaylistPlay Page
All you need to do is check off the items in the track listing, select a playlist from the drop down list, and click the Submit button.
GetArtist Tracklist
In the GetArtist page, the tracklist is not automatically populated due to performance issues. If you click the Fetch All Tracks link in the Artist Tracks section, an Ajax postback will kick off to fetch all the artist's songs.
Removing Tracks from Playlists
To remove tracks from your playlists:
- Click the Playlists link in the header of the page
- In the Manage Playlists section select your play list from the Edit my Playlists line
- Click the Edit button
- Click the Delete button on the left hand side of each track to remove
Using Smart Playlists
Smart play lists are plat lists that don't need to be created manually. They are generated by the system based on certain criteria. Smart play lists are available from the Playlists link in the header of the page.
- 50 Random Songs from Collection
- 50 Newest Songs in the Collection
- 50 Random Songs by Genre (multiple genres)
- 50 Most Played Songs (By You)
- 50 Most Played Songs (By Everyone)
- 50 Random Songs by Star Rating (1-5 stars)
- 50 Highest Rated Songs (By Everyone - may contain duplicates)
In addition the GetArtist page has a built-in smart play list in the Artist Tracks section. You can have the system generate a play list of all tracks from an artist (in order or in shuffled).
Adding Album Reviews
Album reviews can only be added by administrators and managers. To add a review for a CD, click the up arrow image in the Album Review section of the GetAlbum page.
This will open the Album Details page where you can add a review, upload a new cover, and review details about the album. If you click the Fetch button, the cms will try to automatically scrape the album review from AllMusic.com. The Save button saves the review in the database and the Online button links directly to AllMusic.com so you can cut and paste the review.
Scraping reviews using the Fetch button usually has about a 70% success rate for U.S. based albums.
Adding Artist Biographies
Artist biographies can only be added by administrators and managers. To add a bio for an artist, click the up arrow image in the Album Review section of the GetAlbum page. To add a bio for an artist, click the Add/Edit link in the Artist Biography section of the GetArtist page for an artist. Click the Submit button to save the biography in the database.
Adding Song Lyrics
You can save the lyrics of a song in the GetTrack page. Anywhere in the site where you see a track name you can click on it to navigate to the GetTrack page where you can listen to the song, add lyrics, and review details about the track such as its file properties and ID3 header tags.
Clicking the Fetch button to retrieve lyrics connects to the LyricWiki web service and generally has a much higher success rate than the Fetch option for Album reviews.
 Retireving Lyrics for a Song From the Internet |
Viewing File/Track Details
See above... clicking on any track opens the GetTrack page where you can view the file properties, ID3 tags, or listen to the song directly.
Editing ID3Tags
For now this feature remains un-implemented. I'm not sure if we're gonna add this or not at this point.
Shoutcast/Last.fm Radio
This feature is still in the experimental phase. The Last.fm API requires a commercial license to stream music from their service programmatically so the Last.fm streaming probably wont happen.
Getting Help
Developers Guide
Getting the Source Code
We're using Subversion as our source control engine and SourceForge.net to host our SVN repository. Read access is available to everyone so you can either download the source code using subversion or you can browse it on the Apache server.
Click Here for a step-by-step guide to using Subversion with the TortoiseSVN client.
Configuring the Source
Once you have the source code you can't just build it, you have to make a few changes to the configuration. We've partitioned out a few config files so that each time someone makes an edit and commits it the rest of us don't have to keep changing the config files when we do an update (so it will work on our systems).
Developer Instructions for running the VS 2005 project
- Copy all the files in the /config/default folder to /config/my_settings
- Open mp3CMS.sln in Visual Studio 2005
- Rename sample_web.config in the Site project to web/config
- Open/edit web.config and change all instances of ~/config/default to ~/config/my_settings
The first time you run the project in the VS Debugger the database will be created but the scanner will not run. Every future time you run the site, the scanner will execute.
The default login account is:
username: admin
password: password
Object Diagrams
I'm still working on all the documentation but you can review these diagrams:
Contributing Patches & Features
If you'd like to contribute to the project by adding features or submitting bug fixes then:
- Sign-up for a free sourceforge.net account
- Send me your info (via the forum and I will add you as a developer