
Hey, thanks for checking out gmiller.net and this Somerset Kiosk MMC Image maker script.

Here's how to use it.


==============================================================================================
LEGAL AND WHATNOT
==============================================================================================

This code and project files are provided as-is and without warranty. The author is not liable
for any damage to your machines, devices or self. Run at your own risk.

You are free to modify and redistribute this project as you wish, while you must retain an
attribution to gmiller.net.

I do not own the data in the 00-Header file or the 01-Footer file. I assume the data was
property of the now defunct Somerset Entertainment. I'm not sure if it has new owners, or if
it's intellectually protected. Send an email to hypurban86@gmail.com if you feel I need to
remove those bits of code from being downloaded.


==============================================================================================
BEFORE YOU BEGIN
==============================================================================================

The machine this was developed for has 16 album covers, for playing 16 different songs.
This means you'll be expected to use this script with exactly 16 MP3s. More or less and things
will break!

So before you run the script, make sure you've collected the 16 the files you wish to play.

Next, you need to make sure you have an MMC card big enough to store your 16 songs, plus 1.5MB
of overhead.

Before you starting making your image, there are some things you should consider about the 
files you have chosen.


VOLUME
------
Are they all at the same volume? Depending on the mode you set the kiosk to, the files will
most likely be playing back-to-back. If the files aren't all normalized to the same volume it
will become a nuisence to run for long periods.


META-DATA
---------
This machine was designed for bare-bones MP3s. Some modern MP3s have extra binary meta-
data, such as Album Art built into them. If you put an MP3 with such data, it will crash
the kiosk, forcing you to reset it. Use whatever tools you feel comfortable to strip any
unnecessary meta-data.

If you don't know how to sanitize your files, don't worry there's a pretty easy solution.
Get an audio converter program and convert them "from MP3 -> to MP3." Even though that
sounds a bit silly and redundant, when they're converted typically the extra data is dropped.

Note that, when you do a convert there will be a very very small loss of quality, though
it will probably be unnoticable on the Kiosk speakers.

If you decided to normalize the MP3s volume, or you already converted your tracks from
another format, such as FLAC or WMA, chances are your files are good to go. Many files I
tried un-sanitized worked correctly as-is.

It's just important to understand from the beginning that if the machine crashes or plays
garbled noise for certain files, most likely they need to be cleaned up!


FILE SORT ORDER
---------------
Finally, when the script runs, it will sort the MP3s by NAME. If you care about the order,
you can either label them alphabetically, or numerically.

Either of these styles will work:

	A - Monkey Business.mp3
	B - Guybrush.mp3
	C - Fade Away.mp3
	...
	P - Yellow Bird.mp3

			-== OR ==-

	01 - Monkey Business.mp3
	02 - Guybrush.mp3
	03 - Fade Away.mp3
	...
	16 - Yellow Bird.mp3

Whether you chose to label your songs 01-16, or A-P doesn't matter as long as you stick to one
convention.

You don't need to label them at all. If you omit labels, they will be sorted alphabetically
by the file names anyway.



==============================================================================================
USING THE PYTHON SCRIPT
==============================================================================================

This is a python script to generate the binary that goes on the MMC card. We'll talk about how
to get that data on the card below, but for now we'll talk about generating the data.

It should go without saying that this PYTHON script will require your machine to have Python
installed.

This script does not require any additional, non-standard library's.


EASY USAGE
----------
To use it, simply put your MP3s into the "songs" folder that comes with the Python file.

Keep in mind, that you may need to sanitize the mp3s, normalize their volumes, or rename them
to set the order. See "BEFORE YOU BEGIN" above, if you skipped it.

Once you have 16 MP3s (and exactly 16) in the songs folder, run the python file:
"make_mmc_music_image.py"

The only command line arguments it takes are optional, so you can run it anyway you like.
In Windows you can double click the Python file.

If you use a command line, type "python make_mmc_music_image.py" to run the file.

After the script finishs up, a new file called "mmc_image" will be in the directory. This
is the data you will write to the memory card.


ADVANCED USAGE
--------------
Although optional, the python file can take two additional command line arguments.

python make_mmc_music_image.py [folder] [ouput_file_name]

You can specify a folder to look for mp3s in, if you don't wish to use the default ./songs/
directory.

You can also specify a different output file name other than "mmc_image."

NOTE: you must specify a folder if you wish to set the file name. Otherwise the script
will think your output_file_name is a folder to look for mp3s in.

Consider the following examples:

python make_mmc_music_image.py foo

This will tell it to look for MP3s in a folder called ./foo/

python make_mmc_music_image.py foo bar

This will tell it to look for MP3s in a folder called ./foo/ and name the output file "bar"

python make_mmc_music_image.py bar

This will tell it to look for MP3s in a folder called ./bar/ and not affect the output filename.



==============================================================================================
PUTTING THE RESULTING DATA ON AN MMC CARD
==============================================================================================

If you ran the script with default settings, you should now have a file called "mmc_image",
otherwise you'll have the file you specified. For this tutorial, we'll assume it's called
"mmc_image"

I only know how to do this on a Mac, but it's very similar in Linux. No clue about Windows.

For Mac:

	- Insert the MMC card into your computer

	- Close any errors about being unable to mount it (ignore them)

	- Open up a terminal and type "diskutil list"
		This will list all the disks on your machine.
		Look for the MMC card in this list.

		On my machine it was called "/dev/disk2"

	- If the MMC card is mountned, you must first unmount it.
		On the terminal type "diskutil unmount /dev/[path to your disk]"

		Make sure you change [path to your disk] to whatever "diskutil list" told you!

		Make sure it unmounts successfully, the next step wont work if it's still mounted.

	- With the terminal open, navigate to the location of the mmc_image file

	- On the terminal, type "sudo dd if=mmc_image of=/dev/[path to your disk]"
		Make sure to replace mmc_image with whatever file name you chose, if
		you didn't use the default.

		Also make sure to change [path to your disk] to whatever "diskutil list" told you

		BE VERY CAREFUL. You don't want to DD on any other disk than the MMC card.
		You could very easily break your computer if you DD to the wrong disk!

	- Enter your password (because of the sudo) and wait. When the operation completes, you
		will have an MMC card that's ready to try out in your machine!



==============================================================================================
THE PYTHON CODE
==============================================================================================

The code is extremely well commented. Feel free to take a peak, and make any improvements you
see fit. If you'd like to chat about it, or have any questions, feel free to drop me an email
at hypurban86@gmail.com

Maybe this code will work for some other Somerset hardware floating around out there? I'd love
to hear it



==============================================================================================
OTHER
==============================================================================================

If you can tell me how to get into the configuration menu, that would be neat!

If you can figure what some of the other unidentified binary in the image files means, please
let me know! I'm curious.

hypurban86@gmail.com