Copying and Ripping Media

The MME provides capabilities for copying and ripping media. Ripping is the process of reading files from a mediastore, changing the format of these files into another format if required, then writing the files in their new format to a mediastore or other storage device. Copying media is simply ripping media and writing the destination files in the same format as the source files.

About media copying and ripping

You can instruct the MME to rip media from one or several mediastores to any writable mediastore.

The copying and ripping process

When the MME performs a ripping operation, it looks through its copy queue, stored in the copyqueue table, for the IDs of the files to copy or rip, as well as other information it needs for the operation.

If it is copying media, the MME will copy files along with all their metadata. Depending on how it is configured, the MME will either copy all media to one folder or preserve the original folder paths for the copied files on the destination mediastore. For more information, see Managing folder paths below.

The MME will copy or rip a file only if it isn't being played or synchronized. Similarly, the MME will abort a copy or ripping operation if during the operation the source file is requested for playback.

If it is ripping media, the MME uses a metadata database, such as Gracenote, AMG or CD-Text, to add to the metadata of the new ripped file, and uses the ripping template defined through mme_mediacopier_add() to retrieve the folder paths to use when writing the ripped files. For more information, see Copy folder paths and ripping templates below.

When it has received notification that a copy or ripping operation has completed, your client application should use mme_mediacopier_clear() to clear the copy queue so that subsequent copying or ripping operations don't copy or rip the same files twice.

Monitoring progress and playback

Your client application should use mme_mediacopier_get_status() to retrieve the status of media copying and ripping. Copying provides the number of bytes to be copied and the number of bytes copied. Ripping provides the total play time of the media track and the amount of play time ripped. Always check for MME media copying and ripping events (MME_EVENT_MEDIACOPIER_*) to check on the progress of copying and ripping operations, and to know when they are completed.

Priority background ripping

If priority background ripping is set, the MME plays back copied or ripped files from the copied or ripped files, not from the source file.

Event delivery during priority background ripping

During priority background ripping operations, delivery of:

Seeking and trick play during ripping with playback

Attempts to seek forward or perform other trick play activities during priority background ripping can cause undesired output to the user. For example, if the user attempts to seek forward past the current end of a file being played as it is being ripped, he or she may experience a wait, followed by some playback as the ripping catches up to the requested position in the file, further waiting, and so on.

You may, therefore, wish to have your HMI block some or all seek and trick play capabilities during ripping with playback operations, adjusting HMI behavior and displaying appropriate messages to the user as required. You could, for example, grey out buttons for features that you disable until ripping is completed.

As a last fall-through, you may also configure io-media to catch and prevent these operations. The default io-media behavior is to permit seeking and trick play during a ripping with playback operation. However, you can set the MM_TMPFILE_STREAMER_SEEKABLE mmf_graphbuilder resource in the io-media configuration file to prevent these activities.

Copying and ripping media

Copying or ripping with the MME requires that you perform the following tasks, in order:

  1. Check and, if necessary, set the media copying or ripping mode.
  2. For copy operations, decide if you want to preserve the original folder path or use a new path on the target mediastore; for ripping operations, get the ripping template.
  3. Prepare the copy queue with the files you want to copy or rip.
  4. Start the operation.

When it has finished copying or ripping all files in the copy queue, the MME delivers the event MME_EVENT_MEDIACOPIER_COMPLETE.

Setting the copy or ripping mode

To check the copy and ripping mode, use mme_mediacopier_get_mode(); to set the mode, use mme_mediacopier_set_mode().

The MME offers two modes for media copying and ripping:

Both the background and the priority background modes are non-blocking. That is, after you set up the copy or ripping operation and call mme_mediacopier_enable() to start it, the MME starts copying or ripping in the background and your application can go on to perform other tasks. Use mme_mediacopier_get_mode() to retrieve the current media copying and ripping mode. Note that to use priority background media copying and ripping, you must enable this mode in the configuration file mme.conf before starting the MME. For more information, see the chapter Configuring Media Copying and Ripping in the MME Configuration Guide.

The figure below illustrate background ripping:


Background ripping


MME background ripping operation.

The figure below illustrates priority background ripping with playback:


Priority background ripping


MME priority background ripping operation with playback.

Copy folder paths and ripping templates

If you are copying media, you can elect to preserve folder paths; if you are ripping media, you can use ripping templates to define how ripped files will be organized on the target mediastore.

Managing folder paths

The MME can be configured to maintain folder paths by default when copying files by setting the <PreservePath> element in the mme.conf file: <PreservePath enabled="true"/>. For more information, see the chapter Configuring Media Copying and Ripping in the MME Configuration Guide.

If it is configured or instructed to preserve folder paths, when it performs a file copy, the MME:

For example, if a source file is located in /fs/usb0/mymusic/albums/pinkfloyd/wall.mp3, the MME will copy it to /media/drive/ripped/mymusic/albums/pinkfloyd/wall.mp3.

The MME also supports the dynamic setting of folder paths during a copy, which you can select later in the process, when you call mme_mediacopier_enable():


Note: Folder path functionality applies only to media copy operations, not ripping operations.

Using the $*PRESERVE_PATH* template strings

The $*PRESERVE_PATH templates strings may only be used for copying operations. They are not supported for ripping operations.

These template strings:

If you use $PRESERVE_PATH or $NO_PRESERVE_PATH with no additional path information provided, the operation uses the the global default copy destination folder:

$PRESERVE_PATH_AFTER is used in the destination folder name to modify the source path when it is appended to the destination folder. When it builds the destination path, the MME copy operation searchs for and discards from the source path the characters after $PRESERVE_PATH_AFTER: (note the colon “:”). It discards characters from the beginning of the source path up to and including the characters after $PRESERVE_PATH_AFTER:.

For example, to transform the source path /fs/pfs0/Music/Artist/Album/Song.mp3 into /copy_dir/Artist/Album/Song.mp3 on the copied mediastore, you can use either of the following destination paths:

Setting and using ripping templates

The function mme_mediacopier_add() uses the data structure mme_mediacopier_info_t to set templates that define how the MME names ripped files and where it places them in folder structures. If a ripping template is set, when the MME rips media, it automatically names the ripped files and places them in the locations defined by the template, building the folder structures and filling in appropriate information based on the metadata for the ripped files.

For example, the following strings defined for the templates:

Folder
/$ARTIST/$ALBUM/
File name
/$title/

would yield (based on the metadata) the following folders and file names:

Use mme_mediacopier_add() to set ripping templates at any time before a ripping operation and to get the template you want to use before a ripping operation. For example, you could define one template to organize media by artist, album and title, and another to organize media by genre, year and artist, and offer the end-user the option of ripping media using either template. Or, your HMI could let the end-user build additional templates and store them.

Building the copy queue

After you have set the copy or ripping mode you want to use, and how you want to handle folder paths for media copies or the organization of ripped files, you need to compose an SQL query statement and call mme_mediacopier_add() with this statement to:

The example below shows how to add files to the copy queue, ensuring that there are no duplicate entries. The SQL query could be something such as "SELECT fid FROM library WHERE msid=msid_num", where msid_num is the mediastore ID of the CD you want to copy, and you want to select all tracks from the CD for ripping.

// If none of this CD's tracks were ripped before, we make sure
// that we add them to the copyqueue.
if( init_copyqueue ) {
    mme_mediacopier_info_t info;

    // Clear the copyqueue.
    // We do this to prevent copying tracks multiple times.
    mme_mediacopier_clear( mme );

    // Set up rip destination and encoding
    info.dstfilename    = NULL;
    info.dstfolder      = NULL;  // use the defaults
    info.dstmsid        = 0;
    info.encodeformatid = 2;     // 2 is 'wav',
    // see the 'encodeformats' table.

    if( -1 == mme_mediacopier_add( mme, &info, sql, 0 ) ) {
        perror( "mme_mediacopier_add()" );
        return;
    }
}

Note how in the example above, the client application calls mme_mediacopier_clear() to clear the copy queue before adding files to it. For more information, see Managing the copy queue below.

Updating metadata

The MME can be configured to synchronize files with inaccurate metadata before copying or ripping them. If this option is set, when the MME prepares to copy or rip a file, it:

To configure the MME to synchronize files with inaccurate metadata before copying or ripping them, make sure that the <Copying> element <UpdateMetadata> in the MME configuration file (mme.conf) is set to true. This is the default setting.

Completing unknown metadata

To add specified metadata strings when metadata is not known, build the copy queue with the function mme_mediacopier_add_with_metadata() instead of mme_mediacopier_add().

Starting media copying or ripping

To start a media copying or ripping operation, call mme_mediacopier_enable() instructing it to either copy or rip the media listed in the copy queue. This function will read through the copy queue in the copyqueue table and either copy or rip the files, as directed.

Stopping media copying or ripping

To stop a media copying or ripping operation, call mme_mediacopier_disable().

Behavior when media copying or ripping encounters an error

If the MME is unable to copy or rip a file, it:

You may want to remove entries for skipped files from the copyqueue so that the MME does not attempt to copy or rip them the next time you begin a media copying or ripping operation.

You can use the <DeleteOnNonRecoverableError> element in the MME configuration file to have the MME automatically delete from the copy queue entries for files that cause unrecoverable errors.

Behavior when a mediastore is removed

If the mediastore from which files are being copied or ripped is ejected during the operation, the MME will deliver the event MME_EVENT_COPY_ERROR (MME_COPY_ERROR_NOTSPECIFIED) and an event MME_EVENT_MEDIACOPIER_SKIPFID event for the track being ripped, as well as the next few tracks in the copy queue until the MME detects that the mediastore was ejected.

When the MME detects that the mediastore was removed from the system, it delivers the event MME_EVENT_COPY_ERROR (MME_COPY_ERROR_DEVICEREMOVED), and removes the partially ripped file from the destination mediastore.

Managing the copy queue

Stopping a media copying or ripping operation does not affect the copyqueue table. You should ensure that your client application manages the copy queue so that you do not inadvertently copy or rip files left in the queue by an earlier media copying or ripping operation. At the start of every media copying or ripping operation, you should call mme_mediacopier_clear() to remove all entries in the copyqueue table.

You can also remove specific items from the copy queue by calling mme_mediacopier_remove(). This feature allows you to offer the end users functionality such as the ability to review a list of media to be copied or ripped and add or remove individual entries as desired before starting a media copying or ripping operation.

Modifying media metadata

The MME provides mme_metadata_set() so your client application can provide the end-user with the ability to modify the metadata for copied and ripped media. You can design an HMI interface that displays media metadata and accepts input of corrections or additions from the user, then pass the input to the mme_metadata_set(), which will write the modified metadata to both the media file (where applicable) and the MME database.