MME Quickstart Guide

This Quickstart Guide is designed to help you get the QNX Aviage Multimedia Suite up and running on a desktop target system, such as an x86 or a VMware workstation running QNX Neutrino. After you've completed the steps below, you should be able to play some WAVE files on the target system.

Note that the MME is the main component of the QNX Aviage Multimedia Core Package, which is part of the QNX Aviage Multimedia Suite. The MME is used for configuration and control of your multimedia applications.

Contents

  1. Requirements
  2. Uninstall the Multimedia Suite (upgrades only)
  3. Install the runtime files
  4. Copy the SQL schema files
  5. Start io-audio
  6. Start the temporary filesystem
  7. Start the QNX database (qdb)
  8. Start mcd
  9. Start io-media
  10. Give the MME some media to play
  11. Start mme
  12. Check the synchronization
  13. Play some music

Other useful things to try:

If you have problems with the installation or playing media, see:

Instructions for installing the MME on other hosts are included in the MME 1.2.0 Installation Note, available on the QNX website: www.qnx.com/products/.


Note: Read through the complete Quickstart Guide before starting your installation.

Step 1: Requirements

Your target machine needs to be running one of the following:

You need the MME installers:

If you don't have a QNX Momentics CD, you can download an evaluation version from: www.qnx.com/products/. This target machine must also support audio output. For a list of supported audio drivers, go to www.qnx.com/developers/hardware_support/index.html and check the drivers for your platform.

Step 2: Uninstall the Multimedia Suite (upgrades only)

You need to perform this step only if you are upgrading from an older version of the MME. If you are installing the MME for the first time, go to Step 3.

To uninstall the old MME:

  1. Log in as root.
  2. Go to the uninstall directory. For example:
    # cd /usr/qnx641/install/mmedia-core/1.2.0/
  3. Confirm that you are in the right directory. All Neutrino uninstallers are called uninstall.sh, so if you are in the wrong directory you will uninstall the wrong files.
  4. Run the uninstall shell script, uninstall.sh:
    # ./uninstall.sh
  5. Delete the old MME database tables and schema files:
    # cd /db
    # rm *mme* usb*

If you do not know where the MME database and schema files are stored, see your qdb.cfg file for the location of your database. This file is usually located under /db (from the root directory).


Caution: You must update all system components to the current QNX Aviage Multimedia Suite 1.2.0 components. Your environment must contain no 1.2.n or 1.2.0 multimedia components when you begin your installation.

Step 3: Install the MME runtime files

To install the MME runtime files:

  1. Log in as root.
  2. Log into your myQNX account on our website, then go to the Download area.
  3. Download the MME installer, mmedia-core-1.2.0-nnnnnnnnnnn-nto.sh, where nnnnnnnnnnn is an 11-digit build number. The installer is in the form of a shell script.

    Caution: If you are doing an upgrade, first go to Step 2 and uninstall the old MME.

  4. Run chmod to make the script executable. For example:
    # chmod a+x mmedia-core-1.2.0-20071841543-nto.sh
  5. Run the script at the system prompt. For example:
    # ./mmedia-core-1.2.0-20071841543-nto.sh
  6. Follow the instructions on your screen.

Note: If you will be installing more than one Multimedia Suite component, you can enter all the required licenses at this time. You can also enter addditional licenses when you install the components that require them.


Caution: Any client applications that were compiled against QNX Aviage Multimedia Suite (MME) 1.0.n or 1.1.n must be recompiled in order to work with QNX Aviage Multimedia Suite (MME) 1.2.0.

Step 4: Copy the SQL schema files

The MME uses an SQL schema to describe the database tables it uses to store media metadata. You should perform this step every time you get a new version of the MME, because the MME runtime is dependent on a specific schema version.

The MME will use the new schema to generate new tables:

  1. If you are installing the MME for the first time, you need to create a directory for the database:
    # mkdir /db
  2. Copy the new SQL schema and the QDB configuration file:
    # cd $QNX_TARGET
    # cp -c sql/* /db/

Step 5: Start io-audio

You need to run an audio driver in order to hear music:

  1. Check if io-audio is running:
    # pidin | grep io-audio
  2. If io-audio isn't running, you should start it. For example, if audiopci is your audio driver:
    # io-audio -daudiopci
  3. To verify that audio is working correctly on your machine, you can use the Neutrino wave utility to play a sample .wav file. For example, if you have this file on your system, you can use the sample file hallelujah.wav. Any .wav file will do, however:
    # wave /usr/share/audio/hallelujah.wav
    SampleRate = 11025, Channels = 1,
    SampleBits = 8 Format Unsigned 8-bit
    Frag Size 256
    Rate 11025
    Mixer Pcm Group [PCM Subchannel]

Note: Your machine must support audio output. For a list of audio drivers supported for your platform, see www.qnx.com/developers/hardware_support/index.html .

Step 6: Start the temporary filesystem

Now start the temporary filesystem. The MME needs this filesystem running for some of its database tables:

# io-fs-media -d tmp -cpages=4 -cbundles=0

Step 7: Start the QNX database (qdb)

The QNX database (qdb) provides database services to the MME. You must start the database before you start the MME:

# qdb -c /db/qdb.cfg -v -Otempstore=/fs/tmpfs -Rset

The -Otempstore=/fs/tmpfs option is the capital letter “O”. It directs the QBD to use temporary files in a memory location instead of on a disk. This configuration reduces possible disk loads generated by the MME's complex SQL statements. The -Rset option specifies the QDB database recovery mode.

Step 8: Start mcd

The MME uses the Media Content Detector (MCD) utility to detect mediastore availability. The MCD requires a configuration file. The MME installation includes a sample configuration file, mcd.conf, which you can use to get started on systems, such as an x86 or a VMware workstation running QNX Neutrino, that automatically mount CD filesystems.

Start the MCD as follows:

# mcd $QNX_TARGET/etc/mcd.conf

Step 9: Start io-media

The MME requires io-media to decode media. For dlldir, pass in the location where you installed the filters used by io-media. The default location is:

# io-media-generic -M mmf,dlldir=$QNX_TARGET/x86/lib/dll/mmedia

Step 10: Give the MME some media to play

By default, the MME searches recursively for media files along pre-configured paths, starting with /media/drive/, and including /fs/cd0 and /fs/usb0.

The easiest way to give the MME some media to play is to insert a CD or a USB stick with playable media files into your machine. When you start the MME, it will use the MCD utility to detect the mediastore you inserted and synchronize its library with the mediastore.

If you want to play tracks from your hard drive, you must copy them into the directory /media/drive/:

  1. Create the directory /media/drive/ on your target system.
  2. Copy some media files into the directory.

On an x86 platform, the MME supports the following media formats: CDDA and WAVE (standard installation), and MP2, MP3, M4A and WMA (additional licences and runtime files required). The MME may parse other media formats but may not be able to play them because it does not currently have decoders for them.

Step 11: Start mme

You need to specify the path to the mme.conf configuration file at /etc/:

# mme-generic -c $QNX_TARGET/etc/mme.conf

You can now use the qdbc and mmecli utilities to query the database, create a track session, and play some music. The MME installer puts qdbc in the directory /usr/bin/, and mmecli in $QNX_TARGET/target/qnx6/examples/.

Step 12: Check the synchronization

Before playing some files, it's a good idea to confirm that the MME has detected the files in the mediastore you are using, and synchronized them with its library of media.

Use qdbc to query the MME database: point qdbc at the MME database and retrieve the file ID (fid), mediastore ID (msid) and filename (filename) for all media files in the library, as shown below:

# qdbc -d /dev/qdb/mme "select fid,msid,filename from library;"
Rows:3  Cols: 3
Names:  +fid+msid+filename+
00000: |1|1|05 Come Away With Me.wav|
00001: |2|1|09 I've Got to See You Again.wav|
00002: |3|1|12 Nightingale.wav|

The result of the query shown above indicates that the MME sees three WAV files in /media/drive, which has the mediastore ID of 1 (msid=1).

Step 13: Play some music

The MME uses a track session to play media. A track session is defined by an SQL statement that selects one or more files from the database. Use the MME command-line tool mmecli to create and play a track session:

  1. Create a track session. Note that the second argument is the letter “l” (el):
    # mmecli newtrksession l "select fid from library where ftype !=5"
    (rc=0,errno=0) new trksessionid=1
  2. Set the track session. The second argument is the numeral “1” (one). This is the number of the track session you will play.
    # mmecli settrksession 1
    (rc=0,errno=0) trksessionid=1
  3. Play the track session.
    # mmecli play
    (rc=0,errno=0) Playing from track session fid/bid = 0

You should now hear some music.


Note:
  • The SQL statement used to create a track session:
    • must include (at least) the fid of a file to play
    • includes ftype!=5 to exclude entries for mediastores from the track session
    • does not require a final semicolon character
  • The standard MME installation will play CDDA and WAV files only. The MME will synchronize other media file types, but will report an error if you try to play unsupported file types (such as MP3 and WMA files) before installing the runtime files for these codecs. For instructions, see Playing additional formats below.

mmecli commands

Some things to note about the mmecli commands:

Creating a startup script

To simplify MME startup, you can write a simple startup script that performs all the startup steps:

slay -fv io-fs-media qdb io-media-generic mme-generic mcd
io-fs-media -d tmp -cpages=4 -cbundles=0
waitfor /fs/tmpfs
qdb -c /db/qdb.cfg -v -Otempstore=/fs/tmpfs -Rset
waitfor /dev/qdb
mcd $QNX_TARGET/etc/mcd.conf
io-media-generic -M mmf,dlldir=$QNX_TARGET/x86/lib/dll/mmedia
waitfor /dev/io-media/graphs
mme-generic -c $QNX_TARGET/etc/mme.conf
waitfor /dev/mme/default

The startup script above starts the modules required for a simple system. For a more comprehensive system with, for example, the capability to manage and play media from iPod and PFS devices, you would need to add instructions to start the drivers for these devices.

Adding more media files

If you want to add more media files to your system after you've started the MME, you'll need to force it to resynchronize its database.

  1. Add the files to the system.
  2. Get the mediastore ID (msid) of the hard drive:
    # qdbc -d/dev/qdb/mme "select msid,mountpath from mediastores;"
    
    Rows: 2  Cols: 2
    Names:	+msid+mountpath+
    00000:|1|/media/drive|
    00001:|2|/fs/cd0|
    
    

    The second line returned by the QDB lists the table column headings. Thus, the msid for the CD at mountpath /fs/cd0 is 2.

  3. Instruct the MME to resynchronize the mediastore where you added the files:
    # mmecli resync_mediastore msid 0 7
    
    

    To resynchronize files on your hard drive at /media/drive, use its msid, which is 1 (one). Setting the third argument to 0 (zero) tells the MME that no folder is specified, and therefore synchronize the entire mediastore. Setting the last argument to 7 tells the MME to synchronize all information and metadata.

  4. Create and set a new track session, and play the media files, as described in Step 13.

Playing additional file formats

If you want to play file formats (such as MP3 or WMA) not supported by the MME standard installation, you need to install the appropriate runtime files:

  1. Stop io-media.
  2. Follow the instructions in Step 3 for the following installers, as required:
  3. Start io-media.

Using external media players

If you want use an external media player, such as an iPod or a PFS device, you need to:

  1. Install the runtime files that support these devices.
  2. Use iofs-ipod or iofs-pfs, depending on the type of media player.

Note: The arguments for io-usb may be different for embedded targets.

iPods

You can connect to newer iPods (Generation 5 and more recent) either through a serial connection or, with an Apple authentication chip, through a USB connection. Older iPods (Generation 4 and older) support only the serial connection.

Before designing your client application, you should contact Apple to obtain:

For more detailed information about connecting to iPods, see the MME Developer's Guide chapter Working with iPods.

PlaysForSure devices

To set up the MME to play media from PFS devices:

  1. Follow the instructions in Step 3 for the following installers::
  2. If io-usb isn't already running, start it:
    # io-usb -duhci -dohci -dehci
  3. Start the io-fs module for PFS devices:
    # io-fs-media -dpfs
  4. If the MME isn't running, follow the instructions in Step 11 to start it.

Note: When you have finished playing media from an iPod or PFS device, you do not need to disconnect it from the MME. Just physically remove it from the system.

Using USB mediastores

If you want to synchronize USB devices, you need to enable the MME to discover these devices:

  1. If io-usb isn't already running, start it:
    # io-usb -duhci -dohci -dehci
  2. If the QDB isn't running, follow the instructions in Step 7 to start the database.
  3. If you have installed the MME on a target running a QNX Neutrino 6.4.0 release or later, the enum-usb utility enumerates the devices on a USB bus.
    # umass-enum -a -d /dev/ -h umass,umasscd

Note:
  • If you are using the MME installed on VMware, USB doesn't seem to work with all laptops (mainly IBM/Lenovo). The fix is to edit the VMware Configuration File (*.vmx) to add the line: uhci.newCore = "FALSE"
  • USB devices are mounted as read/write devices. To avoid issues such as marking files as busy, or flagging the partition incorrectly, you should unmount a USB device when you have finished with it: # umount /fs/usb0

Sample applications and command-line utilities

You can use the following command line utilities to explore the MME's capabilities:

Troubleshooting

If you have trouble with the installation or playing media, try the following:

If you need to contact us, the information you gather will help us solve your problem.