The 'ultimate' guide to QMC2

From BATCOM-IT Services Wiki
Jump to: navigation, search

Contents

A comprehensive guide to using QMC2 - all information in this guide is based on QMC2 v0.52+ (relevant code changes since v0.52 are listed in this section)

Introduction

QMC2 is a graphical front-end based on Qt for the great M.A.M.E. emulator. As a front-end it needs access to the emulator binary (executable file) and some of its data in order to be useful in any way.

Binary QMC2 packages are meanwhile created for many platforms and distributions (see binary packages in the official QMC2 download section). They should either include everything else that's required or take care of any package dependencies, which usually does not mean that MAME is automatically included as well.

Building QMC2 from source requires a bit more than that and is described in this section.

Starting QMC2 for the first time

When QMC2 is started for the first time, you'll be presented with a welcome dialog asking you for the path to the emulator's executable file and additional data paths.

QMC2-(SDL)MAME welcome screen

You must enter the path to the emulator's executable file. QMC2 will check if the selected binary really is what it's supposed to be after clicking OK. QMC2 will continue loading even if the binary cannot be identified as (some kind of) MAME. Bad things can - and likely will - happen when the binary is not MAME-like / MAME-compatible so take care to select a valid emulator binary here!

For default MAME setups it's sufficient to also set the emulator's working directory to the path where the MAME binary resides and you're done (when you first select/specify the emulator executable and then click the working directory's browse-button, the binary's folder will automatically be suggested).

For non-default MAME setups it's absolutely essential to specify the ROM path explicitly (used as the value of the rompath emulator option, see also ROM path verification below), otherwise the emulator most likely wouldn't find its ROMs. And if you intend to use software-lists (you most probably do) you also have to specify the hash-path (emu-option hashpath) here explicitly. You can also change these settings later in the global emulator configuration, but experience shows that doing it right here will prevent confusion / hassles later :).

When clicking the OK button, QMC2's main widget will be opened and all required data will be read from the emulator (or from caches, if available).

Note that you can get to this welcome screen again by passing the -r (reconfigure) argument on the QMC2 command line. This way you can easily change the most important emulator related settings (i.e. a different binary or working directory) or switch to another GUI style / language before actually starting up. All other settings will be preserved.

Single-instance check

To avoid confusion of the stored setup, it's important that only one instance of QMC2 is running at a time (under the same user's account), so it checks this before it actually starts:

Single-instance check warning message

When you see this message, it simply means that QMC2 thinks another instance of its kind is already running because the corresponding flag in the stored setup hasn't been cleared (yet). However, this could just be the result of a previous crash or an external kill, so don't be surprised when this message box pops up instead of the GUI. Just decide what should be done: exit now, accept once or ignore completely. When you're sure that there's no other instance running, select once!

If you decide to ignore this and multiple instances of QMC2 are currently running under your account, configuration changes may only be valid for the last standing instance! However, this has no impact on the consistency of the data, which means that it's basically not very harmful. So there's an option in the front-end configuration to switch this check on/off at any time. But since some of your recent changes to whatever settings may get lost, we do not recommend to ignore this completely!

Note that by using different configuration paths you still CAN use multiple instances of QMC2 safely!

Also, single-instance checking is not performed for QMC2 Arcade which was designed to cleanly run multiple times.

ROM path verification

Because the ROM path is so essential for making the emulator even work, QMC2 will pop up a warning message if there are any obvious problems with its current setting (i.e. a directory doesn't exist or isn't accessible):

ROM path warning

Additionally you'll find corresponding warnings in the front-end log:

12:54:12.110: WARNING: ROM path '/home/games/mame/roms2' doesn't exist
12:54:12.114: WARNING: ROM path '/home/games/mame/roms3' doesn't exist

Unless you choose to ignore this message it will continue to check the ROM path setting and pop up this warning in case of trouble. The check is done each time after QMC2 has initially loaded the machine list.

The GUI's main widget

Components

The main widget consists of three major components (or areas): the machine list (1), the machine specific details (2) and a collection of widgets with special functions (3):

QMC2's main widget components

The software detail widget is counted as component (4), BTW, and usually takes the place of component (3) unless it's undocked.

General layout

The areas are separated with so called splitters -- a horizontal splitter between (1) and (2)/(3), and a vertical splitter between (2) and (3). You can use these splitters to setup the space each area should take. Any value between 0% and 100% of the space is allowed, so you can even effectively hide a component completely if you will.

The component arrangement as well as the order and visibility of the individual features contained in each component can be configured through the component setup dialog:

Component setup dialog

Should a component be completely disabled (by disabling all its features) the corresponding splitter will be hidden to make room for the remaining components which will automatically maximize to actually use the additional space. When one or more features of the respective component are reenabled, the corresponding splitter is shown again and you'd have to drag it from the corner to its desired place.

The area and orientation in which the tab-widget's header of each component is displayed can be customized through context-menus that are accessible when you right-click a tab-widget's header:

Tab-widget header position and orientation

The North, South, West and East items define the desired tab-header position, the Component setup menu-item would take you directly to the corresponding page of the component setup.

IMPORTANT: Due to a Qt limitation, certain features which are realized as corner widgets (of these tab-widgets) will only work correctly when the tab-header position is set to North or South!

Views

The machine list (1) can be viewed in two or - when also using catver.ini and/or category.ini - in three/four different ways: a full-detail view (also called the master list) which you are presented with in the first place, a hierarchical parent/clone view, a category- and a version-oriented view.

There's a drop-down menu in the bottom area of component (1) to select the view, or you can use the respective menu items and/or their keyboard-shortcuts to switch between views:

View-selection menu and keyboard-shortcuts

Machine list with full detail

This is the main view or master list which contains all XML details read and displayed on demand when you click on the '+' symbols to expand the tree.

It's the only list which can optionally also be filtered by the status of your ROMs. Filtering just means to hide or show items in the list that match your current filter. There's a second drop-down menu only visible in this view (right of the view-selector) to toggle ROM states on and off:

Machine list statistics and the ROM state filter menu

Also note the machine list statistics in the lower left corner. Please refer to this section for an explanation of the letters / colors / counters and their individual meanings.

The progress-bar right of it is used to indicate any active processing on machine items.

On POSIX-compliant systems, there's also an optional physical memory usage indicator (displayed vertically and right of the progress-bar when enabled -- it's shown in the screen-shot above, just below the ROM state filter button / menu).

Hierarchical parent/clone view

The hierarchical parent/clone view visualizes in a tree which sets are clones of other (parent) sets, thus making a smaller (top-level) list in case you're mostly interested in the (still many) different machines there are and which implicit dependencies exist between sets:

Hierarchical parent/clone view

Category view

This view is available when catver.ini and/or category.ini have been downloaded and their use has been activated in the front-end configuration. It shows the machines below the categories they were classified for:

Category view

Version view

This view is also available when the use of catver.ini has been activated. It summarizes machines that were added in a specific version of the emulator:

Version view

Customizing columns

Besides the current sort-order and -criteria (which are global settings), the positions, widths and visibility-states of each view's columns can be customized individually. To switch columns on and off, right-click on a view's header and select the column you want to toggle in the context-menu that's popping up:

Customizing column visibility

There's also Reset item at the end of the column-visibility menu. When activated, this will make all contained columns visible and stretch them equally (it will not reset the column order, though).

Searching for machines

The machine search is a case-insensitive wild-card search that adds implicit globs (*) around each word which can be negated by using ^ for the start of a word or $ for the end of a word.

For example, typing s f z a j results in Street Fighter Zero 2 Alpha (Japan 960805). Entering games$ would display all titles ending in the word games (like '88 Games and a few more). When you'd add a space character after the $, the result would contain titles where the sub-string games is at the end of a word, not ending in it (like Galaxy Games StarPak 2 and others). Same holds for the use of the special ^ character, just specifying the beginning of a title (or a word - not at the beginning of the title - when a space character is added before it).

As you can see, this allows you to navigate to specific machines with a minimum number of keystrokes -- or if you only remember parts of its name, QMC2 can help you to quickly find what you're searching for:

Searching for machines

You can also add the well known wild-card characters * (= any number of characters of any type) and ? (= exactly one character of any type) explicitly if you like. For instance, searching for s f zero?3 produces a slightly more concrete result than just s f zero 3.

The search pattern is matched against the machine descriptions (or long names / titles) as well as their IDs (or short names / set names). So in case of (former) MESS sets, for example, entering search strings like super nintendo or snes would return intersecting results.

Favorites and play-history

You can add machines you like most to the favorites list so you no longer need to search for them. They are sorted in ascending alpha-numerical order.

QMC2 also automatically keeps track of the machines you played (launched). This list will grow over time as you launch more and more sets, and the order in which they are listed corresponds to the time they were played (newest first).

Both lists are saved and restored when the machine list is (re-)loaded (or QMC2 starts/quits) and can be managed through their context-menus.

Note that a more or less complete rewrite is planned for both lists that will morph them into full-featured individual views, and in case of the favorites-list will also allow you to group entries in personal categories.

Machine specific details

Each machine has its own set of related information like images (in-game screen shots, cabinet images, PCB photos etc.), machine specific descriptions, community (web) resources, developer WIP information, local emulator and/or device setups, built-in access to related YouTube videos and more.

All these details are displayed in area (2) of the main widget, and you can freely control which details are to be activated (or disabled) and in which order they are shown in the tab-widget through the component setup dialog (see Tools -> Options... -> Front end -> GUI -> Component setup...):

Component setup (machine detail)

The only detail you can't disable is the emulator configuration tab!

BTW, the order can also be customized directly in the GUI by dragging the tabs around.

Images

QMC2 can handle images of in-game / run-time screen shots (previews), flyers, cabinets, control panels, marquees, title screens and PCBs stored in directories, ZIP- or 7z-archives. Besides that you can define and use as many additional artwork classes as you like.

All images are loaded on demand and kept in an in-memory LRU cache. Its maximum size is 64 MB as per default (this is usually more than enough, but can be changed in the GUI section of the front-end configuration -- the absolute minimum size is 1 MB). This includes software snap-shots, which are no machine details but used in the software-list detail.

Available image formats can be activated/deactivated and prioritized using the format setup dialog that you can reach through the Files / Directories section of the front-end configuration. The default image format which QMC2 uses when nothing else has been specified for a certain artwork class is Portable Network Graphics (PNG).

Note that although machine icons are images as well, they are handled differently in the main GUI and are loaded at once during start-up. Also, they are not kept in the global image cache but in an individual cache (actually a dictionary). The more icons you present to QMC2 (and the larger they are), the more memory will be required for the in-memory icon cache. QMC2 Arcade, however, handles icons exactly in the same way as all other images.

You will have to tell QMC2 where to search for images of which type, which can be done in the front-end configuration.

Please also read this FAQ for more information on how the images have to be stored and what's recommended for best performance!

Emulator configuration

QMC2 configures each emulator it launches from the global setup and optionally overwrites individual parameters with local (or machine-specific) settings, which you can edit on this tab:

Machine specific emulator configuration

There are many options, so it may seem hard to quickly find what you're after. But there's a (hidden) feature which supports you in this: click into the tree-widget with all the emulator configuration options (so it gets the input focus) and start typing the name of the option you're searching for. A small editor-widget will pop up with the text you enter and all matches in the configuration-tree will be high-lighted / expanded as you type. The editor will close itself when escape is pressed or after an idle time of 2 seconds. This works for both the global and the machine-specific settings, BTW.

In case you've previously registered any foreign emulators, the drop-down list on the top of this page would allow you to select a different emulator than the default one. Foreign emulators are not explicitly configured by QMC2, but will be passed the arguments as specified in the registration -- so that's completely up to you! To indicate this, the configuration widget -- as well as the device-mapper and software-list features -- will be disabled (grayed out) when a non-default emulator is selected.

The tool-buttons in the right-most Action column allow you to quickly reset an individual option's value to its global default, to revert the setting to the currently stored value (if any, otherwise the global default value will be used) or to store the respective setting to qmc2.ini (storing can actually mean to remove the setting if it's the same as the global value). The action tool-buttons will be enabled / disabled dynamically, according to their setting's current ini-state. So if a value has been changed, or its value is different than the global default, this will give you a quick indication.

The bottom part of this page allows you to import/export ini-files from/to MAME. In contrast to the global setup, where these functions affect mame.ini, the ini-files meant here are <machinename>.ini.

It's recommended to also read this FAQ for a better understanding of QMC2's way of configuring emulators.

Machine information

Some enthusiasts in the MAME communities collected additional textual information about many of the emulated machines, which QMC2 supports in the form of its so called machine info DB -- a.k.a. history.dat and sysinfo.dat.

When enabled in the front-end configuration and data is available for a specific machine, the information will be interpreted and presented in the following way:

Machine information database

The data is stored in memory when the machine list is (re-)loaded and can optionally be (de-)compressed on-the-fly, which usually saves about 90% of the otherwise required space. In-memory compression makes the initial loading of this data a bit slower, but you won't recognize it anywhere else.

Emulator information

Similar to the machine information, there's another information resource called the emulator info DB -- a.k.a. mameinfo.dat and messinfo.dat. It contains driver-related WIP information from the MAME developers.

When enabled in the front-end configuration and data is available for a specific machine, the information will be shown like this:

Emulator information database

The available data is loaded together with the machine list and can optionally be compressed in memory (see machine information for details).

Software lists

Software-lists themselves are part of MAME (see the hash directory) and QMC2 has to know where this hashpath is in order to scan the available known software and to cache that information for later use.

Make sure the hashpath setting has been set up correctly in the global emulator configuration before going on!

In case you specified a wrong value for hashpath before (or none at all) you'd have to force QMC2 to recreate the software-list cache! To do so, select Tools -> Clean up... -> Clear software-list cache from the menu.

Please note that the use of software-lists requires the software to be stored in the expected way, and QMC2 has no control over this (other than knowing the local ROM paths through the rompath setting). All rules apply in the same way as if QMC2 were not used (in short, with software-lists you pretty much HAVE TO use <rompath>/<software-list-name>/<software-name>.zip -- for details, see the MESS User's Manual).

Software list

When the software-list data is not cached (or not current), initial loading will require a bit of time and you'll have to wait until the data has been fully scanned. Cached data will load much faster.

The list of known software for the currently selected system contains all software entries that are available for it, sometimes even from multiple lists.

Software entries you like most can be added to the favorites list. This includes the ability to combine the saved entry with a previously created device configuration (selected from the drop-down menu on the top of this page).

You can search within the known software on the search page of this widget, which uses a similar algorithm and pattern-syntax as the machine search.

All pages allow for directly launching the emulator with a selected software, either from the context-menu of each entry or via the tool buttons on the top.

The columns of each of the three lists can be customized in the same way as the columns of the machine list views.

Use the reload button (top-left) to reload all data related to the current system's software-list(s) from cache.

Right of it you'll find a toggle-button (filter icon) for software-compatibility filtering: when enabled, only software-titles that are supposed to be compatible with the respective model of this system will be shown (for instance NTSC/US vs. PAL/EU models). Of course, this only works when that sort of information is included in the software-list's data (which is true for just a few lists) and ignored otherwise.

The second toggle-button (magnifier icon) will enable/disable the software-detail widget, a special widget which will be shown as a (temporary) replacement for component (3).

The third toggle-button (ROM icon) will enable/disable software-state checking & caching. Just as with system ROMs, software sets have similar states which will be indicated as colored icons on the Title column. When enabled, a drop-down menu will be attached to the button (hold button down to open it) where you'll find the actual action to check software-states.

Right of the software-state button you'll find two additional tool buttons that have attached menus for analyzing and rebuilding the current software or complete software-lists. These ROMAlyzer actions are also available through the context-menu of a software item, BTW. Depending on your current ROMAlyzer configuration, the rebuild software menu (button) may not be available, though.

The following two toggle-buttons (camera icon / flag icon) will enable/disable the so called automatic snap- or state-name adjustment. When one or both of these features are enabled, QMC2 will launch the emulator with suitable values for the -snapname and/or -statename parameters so that it creates clean path-names for snapshot (F12) and/or save-state files (Shift-F7). As per default, snapshot images are chosen in a way so that they can directly be used with the software-list feature - without the hassle of renaming / reorganizing images afterwards (but you may still have to move them to a different folder perhaps, depends on your setup) - and save-state files will be cleanly separated in sub-dirs below the state-directory. You can also customize the exact naming patterns if you will -- hold either button down for its menu and select Adjust pattern!

The tool-buttons on the right are for exporting the current system's software-list(s) to another format (ASCII or CSV), for favorites management and to launch the system with the software-parts mounted on suitable devices (see next section).

Mounting software-parts manually

Software-list entries can consist of one or multiple parts, that is, the disk-, CD-, cartridge- or whatever-images which made up said software at the time of its publication.

QMC2 will usually decide on what part(s) are to be mounted on which device(s) automatically, and this algorithm mainly depends on the following things:

  • The available devices for the current machine
  • The available interfaces of these devices (for instance, a 5,25" floppy-disk wouldn't fit into a 3,5" drive)
  • The order in which the parts are listed in the software-list entry (for instance, when there's just one suitable floppy-drive, only 'flop1' can be mounted, when there is a second drive, 'flop2' will also be mounted, and so on)

This auto-mount mode will never mix parts from different software-list entries, but use the currently selected software's parts and nothing else.

That's nice for most software, but if you would like to have full control over what is mounted where, you're free to do so:

Software list mount device selection

The megatech driver is a nice example because it directly shows what you can achieve with it.

Note that both modes (manual vs. automatic) are mutually exclusive. That is, devices are either mounted automatically or manually.

Also note that there may be software-list entries containing parts that are not compatible with any device interface, in which case QMC2 will simply not allow you to mount them (as the emulator wouldn't mount them as well, whatever you might try, at least not as parts from a software-list entry). This could be a wanted situation when an entry is just a placeholder for future use, so there's basically nothing wrong with that, but it could also be a bug of the software-list or -entry in question. If unsure, please contact the MAME developers (and not us).

Software snaps

QMC2 also supports so called software snaps, that is run-time / in-game snapshots from any known software contained in software-lists, displayed in their original size. This is shown in the screen shot above.

Software snapshots need to be placed in a separate directory (or ZIP-/7z-archive), and its sub-directory structure has to reflect the software-list names for which the respective images are valid.

For instance, software snapshots for the gamegear software-list have to be stored in a gamegear sub-directory, and image files in that folder must be named exactly as their entry names in the software-list, followed by a supported and activated format extension (for example <software-snap-folder>/gamegear/aladdin.png). This applies to both the directory- and the ZIP-/7z-based storage of software-snaps (in case of a ZIP-/7z-archive <software-snap-folder> is omitted, of course).

As mentioned above, software-snapshots will also be stored in the global image cache.

Please refer to the front-end configuration to setup the software-snap folder as well as the placement and activation of the snapshot-viewer.

Software detail-widget

There are so many known software titles nowadays that a specific widget with detailed information about those seemed reasonable (and was thus requested by our users).

QMC2 includes such a widget which, if enabled, will reuse the space of component (3) whenever necessary. This so called software detail widget (a.k.a. component (4)) is the first of a new class of widgets which can be docked or undocked at any time (through the tool-button in its top-right corner: Dock/undock button). When undocked (or floating), the space of component (3) will not be used, but instead the widget will pop-up as an independent window giving you full control over its size and position.

The software-specific details that are covered by this widget and explained in the following sections are: a scaling snapshot-viewer, a ProjectMESS look-up feature, an editor/viewer for personal notes about each software and a (read-only) software-info browser. This list may be expanded with additional details in the future, if applicable.

Software snapshots

The same software-snapshots as discussed above are displayed in the Snapshot tab of the software-detail widget, but this time optionally (smoothly) scaled to fit the widget's view-port. It shares the image cache-slots of its unscaled pendant and is thus just an alternative view to the same data:

Software snapshot (software detail widget)
ProjectMESS look-up

The ProjectMESS web-site is the number one resource of aggregated information concerning software lists on the internet, so inclusion of an automated look-up of said information seemed reasonable and thus found its way into the software-detail widget on the ProjectMESS tab:

ProjectMESS look-up (software detail widget)
Software notes

The Software notes tab allows for making personal rich-text (HTML) notes about individual software-titles.

The notes-viewer is a WYSIWYG editor in itself. Its WYSIWYG-editing capabilities are usually sufficient for most cases, but they are still limited to what can be done through the execCommand() JavaScript function in WebKit, so there's also a text-editor which lets you manually change the HTML code whenever there are special requirements:

Personal software notes, WYSIWYG (software detail widget) Personal software notes, HTML (software detail widget)

Please also see the software-notes folder / template settings in the front-end configuration section for more information about the storage of software-notes and how to use a template to make note-editing easier.

BTW, technically inclined / interested users might want to pay attention to the fact that the HTML editor is a nested QMainWindow with its own menu- and tool-bars, which is supposed to be impossible in Qt :). It's based on the HTML editor from the Qt Labs graphics-dojo project, heavily revised with regard to its functionality and to be used within QMC2.

Software information

Besides MAME history information, recent versions of arcade-history.com's history.dat also include a bug load of similar stuff for software-packages that are part of software-lists. The software-detail contains a software info tab that displays corresponding contents from the so called software info DB when you enable / configure it in the front-end's files / directories section of the setup dialog.

Software information (software detail widget)

Device configurations

Many drivers can run without it (i.e. most calculators or chess computers), but anytime you want to be able to read or write from/to some device, you'll have to tell MAME what file it should use for which device instance.

Device mappings

The legacy way to map files to devices in QMC2 is through the device mappings tab:

Device mappings

To create a new device configuration, click on the left-most tool button from the button-group in the top-right area of the dialog.

Each configuration has to have a unique name, so either enter a new name or simply choose a file for an instance and let QMC2 select the configuration name for you (it's derived from the name of the first selected file, and will automatically be named uniquely).

To save the device configuration, press the right-most button, which will now be enabled. The new setup will then be added to the list of stored device configurations in the bottom area. A configuration contained in this list can be played as usual, or cloned, edited and removed (see context-menu and corresponding tool buttons).

Note that when you're making changes to an existing device configuration and play that selection, the configuration changes are saved automatically (or implicitly)!

Slot options

A number of systems also support slots where a selection of emulated devices can be plugged. This may also be saved as part of a device configuration and can be set up on the second tab:

Slot options

Note that the available slots and device instances are dynamically updated whenever a device (here: a slot option) is plugged or unplugged, and nested slots may appear or disappear because of this as well.

For slot-devices that support BIOS selections, you'll also get a drop-down list in the right-most column where you can choose the BIOS from.

File chooser

The probably most popular method of configuring devices is the newer file chooser, which will allow you to select and automatically map any free-standing files within your file-system with just a few clicks:

File chooser

The file chooser will read directory contents in a separate thread and will never block the GUI, even on folders with 10.000 or many more files. The LCD counter in the bar on the top will indicate the progress of current scanning activity, which can be interrupted at any time (i.e. by choosing a different folder, changing the search-text, selecting a different driver, ...).

Note that the file chooser can directly handle ZIP or 7z contents (handled much like folders), so you can directly map files within ZIP/7z-archives!

These 1:1 (instance:file) mappings can optionally also be saved as device configurations, which can be achieved by pressing the left-most button on the top. Select the device instance from the drop-down list next to it, and/or let QMC2 automatically choose one for you from the extension of the currently selected file's name (toggled by the check-able button right of the instance-chooser).

In case you would like to merge the currently set device-mappings with the 1:1 file-chooser mapping, you have to activate this behavior through the merge toggle-button (Merge-maps.png). Of course, when there's an instance-overlap the mapping made with the file-chooser will overwrite the one made on the device mappings page.

Note that slot-options are implicitly honored by the file-chooser. So whenever you've set up any slot-options that change the available devices (and their interfaces), the instance drop-down list will be refreshed accordingly.

ProjectMESS system look-up

This is (web) look-up for ProjectMESS's system info pages:

ProjectMESS system look-up

YouTube videos and local movie files

FIXME: YouTube data API v3 is currently not supported! As of v0.54 the "Search videos" tab is hidden because of this, the rest should work fine though.

Another online resource QMC2 supports directly is YouTube. This feature includes support for local movie files as well.

Quite a large number of videos related to arcade games, consoles, old computer hard- and software and the emulation of those is available on YouTube nowadays, so it seemed reasonable to create a built-in video player for it (admittedly, the motivation was also driven by technical interests of its author). It's really not just a gimmick, but a very useful feature.

YouTube video widget

You can use the search videos page to find any related videos as well as to play and/or attach them to the current machine (attaching of videos is also possible by pasting a YouTube video URL from the clipboard on the attached videos page or on the video-player itself, BTW).

Attached videos will include thumbnail images, and these images will be cached on disk together with other relevant video information (YouTube cache). This is done mainly because YouTube doesn't like it when such information is requested too often (which could lead to your IP address being blocked by YouTube, so this has to be avoided!).

The video player itself (shown in the screen shot above) allows you to select the preferred video-format and -quality from FLV 240P up to MP4 3072P, corresponding to YouTube's video format IDs 5, 18, 22, 34, 35, 37 and 38 -- see this Wikipedia article for details. It's based on the Phonon multimedia framework, does not require Flash (but good FLV and MP4 codecs!) and renders even HD videos very nicely. If the preferred video format/quality is not available, QMC2 automatically falls back to the next highest format.

Please also check out the player's context-menu for further functionality like full-screen playback, player-control and links to corresponding YouTube sites. Note that when the player is in full-screen mode, the only way to return to windowed mode is by pressing the full-screen toggle shortcut-key, which is F11 as per default (the menu item's text will tell you what the key-sequence is, a corresponding message will also be presented in a semi-transparent overlay text-widget after the player has entered full-screen mode).

Also note that embedded playing may be disallowed for some videos. You should get a corresponding warning message in the front-end log in these cases and the playback would not start. Same basically holds for material which isn't allowed to be played in your country, or any arbitrary errors.

A typical error message (i.e. for some music videos watched from Germany) may look like this:

09:55:27.593: video player: video info error: ID = 'xXxXxXxXxX', status = 'fail', errorCode = '150', errorText = '...'

But music videos aren't what we want to watch anyway, right Smile :)!!?

You'll basically have the same restrictions (if any) as with a browser-embedded Flash-Player.

System notes

Just as with software notes, you can store personal rich-text notes about each machine (or system) on the system notes detail tab:

System notes

Please also see the system-notes folder / template settings in the front-end configuration section for more information about the storage of system-notes and how to use a template to make note-editing easier.

Special widgets

Component (3) of the main widget consists of the front-end and emulator logs, the emulator control panel, a built-in audio player and a simple download manager.

Front-end log

The front-end logs many things, and informs you of any actions it currently takes. It's the number one resource for trouble-shooting in case something goes wrong.

Besides any warnings or fatal error messages it also contains statistical information, many counters, provides feedback to the emulators it currently manages, and includes performance-related information such as timers for a number of initialization steps and jobs (like a ROM audit).

Front-end log

QMC2's front-end log is also written to file in the QMC2 configuration path (overwritten every time you restart QMC2), named qmc2-<variant>.log (i. e. qmc2-sdlmame.log or qmc2-mame.log).

Emulator log

The emulator log contains all output running emulators may produce to stdout or stderr.

QMC2 carries an internal sequence number for the emulators it launches (#0, #1, #2, ...), and this number will be shown as part of every message to distinguish between the output from multiple emulators:

Emulator log

QMC2's emulator log is also written to file in the QMC2 configuration path (overwritten every time you restart QMC2 and launch at least one emulation), named mame.log.

Emulator control panel

The emulator control panel lists every currently running emulator launched by and under control of QMC2, together with its internal ID, the name of the driver, the emulator's process ID (PID), the current status of the emulation (paused/running/stopped), any output notifier names and values the emulation might produce (the first three LEDs are handled individually, the rest of the notifiers will be displayed as child-items in a tree) and the command used to spawn the process:

Emulator control panel

Please refer to the list's context-menu for available actions related to running emulators.

Audio player

Well, OK, this one really IS a gimmick feature -- but having a built-in audio player that knows when it has to shut up may still be useful Smile :)!!

Audio player

The audio player utilizes the Phonon multimedia framework and should play all audio formats the backend API supports. The major player controls are also available as keyboard-shortcuts and should thus even be controllable on cabinet-systems.

The front-end log will contain ID tag information whenever a new track is started:

18:35:40.995: audio player: track info: title = '2 Minutes To Midnight', artist = 'Iron Maiden', album = 'Powerslave', genre = 'Metal'

You can also use it for many audio-streams (MP3, Ogg-Vorbis, etc.), and when the stream contains that information, you'll be informed about new tracks as well:

18:39:58.416: audio player: track info: title = 'ROCK ANTENNE Heavy Metal', artist = '', album = 'ROCK ANTENNE Heavy Metal', genre = 'Rock'
18:39:58.564: audio player: track info: title = 'MEGADETH - Set the world afire', artist = '', album = 'ROCK ANTENNE Heavy Metal', genre = 'Rock'

Download manager

Every download issued by the MiniWebBrowser will be added to the download manager:

Download manager

When you enable the remove finished check-box, finished downloads are automatically removed from the download manager after they've been received completely (but not when there has been some error).

Additionally, you'll find feedback about all downloads in the front-end log:

14:16:04.484: download started: URL = http://qmc2.arcadehits.net/flyers/k.zip, local path = /home/rene/k.zip, reply ID = 280939072
14:16:05.810: download finished: URL = http://qmc2.arcadehits.net/flyers/k.zip, local path = /home/rene/k.zip, reply ID = 280939072

Notes-templates

Creating system- and software-notes can be a very time-consuming task, especially if you would like your notes to all look quite similar (with regard to their formatting and the information they provide), so QMC2 allows you to specify an HTML file that's used as a template for automatic generation of notes. When templates are used, data will only be saved on disk when it's different than what the template creates, so you can use this in conjunction with your personal notes. Don't be surprised, though, that saving a note can actually result in the removal of a file -- if, and only if, there's no customized data!

Notes-templates can use macros which will be replaced with real data before rendering the HTML. See the tables below for details.

IMPORTANT: When editing notes-templates, make sure that the editor supports UTF-8 and stores the file with this character encoding, otherwise certain characters may not be displayed correctly!

Using JavaScript

Notes templates can also include some logic through JavaScript, so you can build templates that are extremely flexible.

Note that all code contained in <script> ... </script> blocks will be filtered whenever needed! If you want your JavaScript code to survive the filtering, use <script language="JavaScript"> ... </script>. However, any code that produces/changes the document's content must be filtered and cannot be used in this way!

You can also access the notes-editor object itself which is exposed to JavaScript as qmc2NotesEditorObject (or qmc2NEO). This allows you to call its slots (JS-invokable methods/functions) and/or access its data members directly from your JavaScript template. Unless otherwise stated by the developers (i.e. in this document) the only things you are allowed to do is calling the slots described in the following sections. Everything else can be considered dangerous and is thus unsupported!

Image- and color-selection dialogs

  • qmc2NEO.getColor([currentColor])
    • Opens a color-selection dialog and returns the selected color as an HTML color code string (#rrggbb).
    • If currentColor is given, non-empty and valid, the dialog will use it as the initially selected color.
    • Returns the value of currentColor (or an empty string when currentColor wasn't passed) when the Cancel button is pressed.
    • Example:
function selectColor() {
        var color = localStorage['Example/SystemNotesTemplate/BackgroundColor'];
        color = qmc2NEO.getColor(color);
        localStorage['Example/SystemNotesTemplate/BackgroundColor'] = color;
        if ( localStorage['Example/SystemNotesTemplate/BackgroundMode'] == 'color' )
                qmc2NEO.loadCurrentTemplate();
}
  • qmc2NEO.getImage([currentImage])
    • Opens a file-selection dialog and returns the chosen (image) file's absolute path.
    • If currentImage is given, non-empty and the file/path exists, the dialog will use it as the initially selected file/path.
    • Returns the value of currentImage (or an empty string when currentImage wasn't passed) when the Cancel button is pressed.
    • Example:
function selectImage() {
        var image = localStorage['Example/SystemNotesTemplate/BackgroundImage'];
        image = qmc2NEO.getImage(image);
        localStorage['Example/SystemNotesTemplate/BackgroundImage'] = image;
        var mode = localStorage['Example/SystemNotesTemplate/BackgroundMode'];
        if ( mode == 'image-tiled' || mode == 'image-scaled' )
                qmc2NEO.loadCurrentTemplate();
}

Accessing image data of built-in artwork classes

  • qmc2NEO.isZippedImage(imageType)
    • Determines if the image for a given imageType is loaded from a ZIP/7-zip archive or not.
    • Use one of these for imageType: 'prv' (preview), 'fly' (flyer), 'cab' (cabinet), 'ctl' (controller), 'mrq' (marquee/logo), 'ttl' (title), 'pcb' (PCB) or 'sws' (software-snapshot).
    • Returns true if the image is loaded from a ZIP/7-zip archive or false if images are loaded from regular folders/files.
    • Example:
if ( qmc2NEO.isZippedImage('cab') )
        document.write(tr('Cabinet images are loaded from a ZIP or 7-zip archive!'));
else
        document.write(tr('Cabinet images are loaded from file URLs!'));
  • qmc2NEO.getImageData(imageType)
    • Returns the base64-encoded image data for a given imageType which you can use in <img> tags, or an empty string when something went wrong.
    • Use one of these for imageType: 'prv' (preview), 'fly' (flyer), 'cab' (cabinet), 'ctl' (controller), 'mrq' (marquee/logo), 'ttl' (title), 'pcb' (PCB) or 'sws' (software-snapshot).
    • When there's no image available for the currently selected machine, qmc2NEO.getImageData() returns the base64-encoded version of the Ghostbusters image instead.
    • Warning: The HTML can become really big for large images, and this will slow down image loading dramatically (also because it cannot be done asynchronously in this case)! So if you want notes-templates to perform nicely, you have to use folder-based image storage!
    • Example:
function imageTag(imageType) {
        var imgTag = "<img src=\"data:image/png;base64," + qmc2NEO.getImageData(imageType) + "\"/>";
        return imgTag;
}
  • qmc2NEO.getIconData()
    • Returns the base64-encoded icon data for the currently selected machine which you can use in <img> tags.
    • When there's no icon available, qmc2NEO.getIconData() returns an empty string.
    • Example:
function iconTag() {
        var data = qmc2NEO.getIconData();
        var imgTag = "<img src=\"";
        if ( data ==  )
                imgTag += "$GHOST_IMAGE$\"/>";
        else
                imgTag += "data:image/png;base64," + data + "\"/>";
        return imgTag;
}

Accessing image data of custom artwork classes

  • qmc2NEO.customSystemArtwork()
    • Returns a string-list containing the names of all available custom artwork classes targeted for systems.
    • Note that system artwork names may contain ampersands (&) for defining accelerator key-sequences, so you have to replace all occurrences of '&' with an empty string before displaying it as an artwork's name.
  • qmc2NEO.customSoftwareArtwork()
    • Returns a string-list containing the names of all available custom artwork classes targeted for software.
    • Note that software artwork names may contain ampersands (&) for defining accelerator key-sequences, so you have to replace all occurrences of '&' with an empty string before displaying it as an artwork's name.
  • qmc2NEO.customArtworkZipped(artworkName)
    • Determines if the custom artwork class artworkName is loaded from a ZIP/7-zip archive or not.
    • Returns true if images are loaded from a ZIP/7-zip archive or false if images are loaded from regular folders/files.
  • qmc2NEO.customSystemArtworkUrl(id, artworkName)
    • Returns the file URL of the custom system artwork artworkName for system id.
    • Example:
var customArtworkNames = qmc2NEO.customSystemArtwork();
if ( customArtworkNames.length > 0 ) {
    for (var i = 0; i < customArtworkNames.length; i++) {
        var artworkName = customArtworkNames[i];
        var readableArtworkName = artworkName.replace("&", "");
        document.write("<p><b>" + readableArtworkName + "</b></p>");
        if ( qmc2NEO.customArtworkZipped(artworkName) )
            document.write("<img width=\"50%\" src=\"data:image/png;base64," + qmc2NEO.customSystemArtworkData('$ID$', artworkName) + "\">");
        else
            document.write("<img width=\"50%\" src=\"" + qmc2NEO.customSystemArtworkUrl('$ID$', artworkName) + "\">");
    }
}
  • qmc2NEO.customSystemArtworkData(id, artworkName)
    • Returns the base64-encoded image data of the custom system artwork artworkName for system id.
  • qmc2NEO.customSoftwareArtworkUrl(listName, softwareName, artworkName)
    • Returns the file URL of the custom software artwork artworkName for software softwareName from software-list listName.
    • Example:
var customArtworkNames = qmc2NEO.customSoftwareArtwork();
if ( customArtworkNames.length > 0 ) {
    for (var i = 0; i < customArtworkNames.length; i++) {
        var artworkName = customArtworkNames[i];
        var readableArtworkName = artworkName.replace("&", "");
        document.write("<p><b>" + readableArtworkName + "</b></p>");
        if ( qmc2NEO.customArtworkZipped(artworkName) )
            document.write("<img width=\"50%\" src=\"data:image/png;base64," + qmc2NEO.customSoftwareArtworkData('$SOFTWARE_LIST$', '$SOFTWARE_NAME$', artworkName) + "\">");
        else
            document.write("<img width=\"50%\" src=\"" + qmc2NEO.customSoftwareArtworkUrl('$SOFTWARE_LIST$', '$SOFTWARE_NAME$', artworkName) + "\">");
    }
}
  • qmc2NEO.customSoftwareArtworkData(listName, softwareName, artworkName)
    • Returns the base64-encoded image data of the custom software artwork artworkName for software softwareName from software-list listName.

Querying XML data

  • qmc2NEO.queryLocalXml(id, queryString, sort, systemEntityName)
    • Performs an XQuery passed in queryString on the XML data from the system id.
    • The optional boolean parameter sort specifies if the result list should be sorted or not (default: true).
    • The optional string parameter systemEntityName was used to replace <machine> XML entities with a different name that you selected so you didn't need to change the query in case of different emulator variants. This is obsolete since v0.52 because there's only MAME now (i.e. the entity name is always <machine>). If systemEntityName isn't an empty string, the given name must not be used by any (sub-)entities or attributes, so choose your poison wisely! Otherwise the data is not changed before the query is executed (default and backward-compatible behavior).
    • Note: The query must evaluate to string(s)! Otherwise the result may be empty.
    • Returns true when the query was valid and performed successfully, otherwise returns false.
    • The XQuery variable $xmlDocument is predefined from C++ and bound to the actual XML data. You should specify it somewhere in your query to reference the XML in the form of doc($xmlDocument) (see example below). If the passed query misses this variable binding it's automatically prepended to the query string.
    • Note that there's also a shorter alias function name for this (same parameter list): qmc2NEO.queryXml(id, queryString, sort, systemEntityName)
  • qmc2NEO.getXmlResult()
    • Returns the result of the last XML query performed by qmc2NEO.queryLocalXml() as an array of strings (which may be empty if there were no matches or when the query failed).
    • Example:
document.write("<h3>" + tr('Software lists') + "</h3>");
if ( qmc2NEO.queryLocalXml("$ID$", "doc($xmlDocument)//system/softwarelist/@name/string()", true, "system") ) {
        var result = qmc2NEO.getXmlResult();
        if ( result.length > 0 ) {
                document.write("<p>" + tr('Associated software-lists:'));
                for (var i = 0; i < result.length; i++)
                        document.write((i > 0 ? ", " : " ") + result[i]);
                document.write("</p>");
        } else
                document.write("<p>" + tr('This system has no associated software-lists.') + "</p>");
} else
        document.write(tr('XML query error!'));

Video snaps

  • qmc2NEO.videoSnapUrls(id)
    • Returns a list of file URLs of all videos valid for the system id and contained in any of your video snap folders.
    • Example:
...
<style type="text/css">
    ...
    video::-webkit-media-controls-fullscreen-button {
        display:none !important;
    }
    video::-webkit-media-controls-current-time-display {
        display:none !important;
    }
    ...
</style>
...
<script>
    var vsUrls = qmc2NEO.videoSnapUrls("$ID$");
    if ( vsUrls.length > 0 ) {
        document.write("<h4>" + tr("Video snaps") + "</h4>");
        document.write("<video controls loop autoplay>");
        for (var i = 0; i < vsUrls.length; i++)
            document.write("<source src=\"" + vsUrls[i] + "\" />");
        document.write("</video>");
    }
</script>
...

DAT-info access functions

  • qmc2NEO.systemInfo(id)
    • Returns the system-info string for the machine named id, or the translated text for "no data available" if there's no info entry.
    • Example:
document.write("<h4>" + tr("System info") + "</h4>" + qmc2NEO.systemInfo("$ID$"));
  • qmc2NEO.emuInfo(id)
    • Returns the emulator-info string for the machine named id, or the translated text for "no data available" if there's no info entry.
    • Example:
document.write("<h4>" + tr("Emulator info") + "</h4>" + qmc2NEO.emuInfo("$ID$"));
  • qmc2NEO.softwareInfo(list, id)
    • Returns the software-info string for the software named id from the software-list list, or the translated text for "no data available" if there's no info entry.
    • Example:
document.write("<h4>" + tr("Software info") + "</h4>" + qmc2NEO.softwareInfo("$SOFTWARE_LIST$", "$SOFTWARE_NAME$"));

Miscellaneous functions

  • qmc2NEO.loadCurrentTemplate()
    • Causes a reload of the current template (and returns true on successful completion or false in case of any error).
    • This is useful whenever settings are changed that influence the template's look, and if you would like those settings to be applied on-the-fly.
    • Note that there's an alias function for the same purpose: qmc2NEO.reloadTemplate()
    • Example:
function toggleHeaderFixed(enable) {
        localStorage['Example/SystemNotesTemplate/HeaderFixed'] = enable ? 'true' : 'false';
        qmc2NEO.loadCurrentTemplate();
}
  • qmc2NEO.isBios(id)
    • Returns the boolean value true when the machine named id is a BIOS set, otherwise returns false.
    • Example:
if ( qmc2NEO.isBios("$ID$") )
        document.write("$ID$ " + tr('is a BIOS set!'));
  • qmc2NEO.isDevice(id)
    • Returns the boolean value true when the machine named id is a device set, otherwise returns false.
    • Example:
if ( qmc2NEO.isDevice("$ID$") )
        document.write("$ID$ " + tr('is a device set!'));
  • qmc2NEO.romStatus(id, translated)
    • Returns the ROM status string for the machine named id; when the optional boolean parameter translated is true (default false) the returned string will be translated.
    • Example:
document.write(tr('ROM status for') + " $ID$: " + qmc2NEO.romStatus("$ID$", true));
  • qmc2NEO.rank(id)
    • Returns the personal rank (an integer value from 0 to 5, inclusively) for the machine named id; the value 0 means that the system has no associated rank.
    • Example:
document.write(tr('Rank for') + " $ID$: " + qmc2NEO.rank("$ID$"));
  • qmc2NEO.comment(id)
    • WIP-info: this function is reserved for future use and will always return an empty string!
    • Returns the personal comment for the machine named id, or an empty string (default) if the system has no associated comment.
    • Example:
document.write(tr('Comment for') + " $ID$: " + qmc2NEO.comment("$ID$"));
  • qmc2NEO.openLinkInDefaultBrowser(linkUrl)
    • Opens the given linkUrl in the system's default browser (whatever that is) -- this can be useful when QMC2's built-in browser has issues with a URL or doesn't support a required protocol.
    • Example:
qmc2NEO.openLinkInDefaultBrowser("https://github.com/mamedev/mame/blob/master/src/mame/drivers/kickgoal.c");

Using HTML5 localStorage for template-settings

You also have the ability to store settings as key/value (string) pairs via the HTML5 localStorage API:

// writing a setting
localStorage['key'] = 'value';

// reading a setting
document.write("<p>The stored value is " + localStorage['key'] + ".</p>");

System-notes template macros

Macros for data from the machine-list:

Macro

Description

$DESCRIPTION$ System's title / description
$ID$ System's name / ID
$PARENT_ID$ Parent's name / ID (empty if there is no parent)
$MANUFACTURER$ The manufacturer of this system
$YEAR$ The year this system was first published
$CATEGORY$ The category of this machine
$VERSION$ Emulator version this machine was added
$PLAYERS$ Number of players (or separate input devices)
$ROM_TYPES$ Types of dumps included in the set (ROM/CHD)
$DRIVER_STATUS$ The maturity status of the driver (translated)
$DRIVER_STATUS_UT$ The maturity status of the driver (untranslated)
$ROM_STATUS$ The system-set's status (translated), see ROM states
$ROM_STATUS_UT$ The system-set's status (untranslated), see ROM states
$SOURCE_FILE$ The driver's source file name
$IS_BIOS$ Set to "true" if the current machine is a BIOS set, otherwise set to "false"
$IS_DEVICE$ Set to "true" if the current machine is a device set, otherwise set to "false"

Image / video macros:

Macro

Description

$PREVIEW_IMAGE$ Current system's preview image
$FLYER_IMAGE$ Current system's flyer image
$CABINET_IMAGE$ Current system's cabinet image
$CONTROLLER_IMAGE$ Current system's controller image
$MARQUEE_IMAGE$ Current system's marquee image
$LOGO_IMAGE$ Alias for $MARQUEE_IMAGE$
$TITLE_IMAGE$ Current system's title image
$PCB_IMAGE$ Current system's PCB image
$GHOST_IMAGE$ Path to the Ghostbusters logo (if an image wasn't found, its file URL will be same as the value of this macro, so you can use it to check image validity)
$VIDEO_SNAP_URL$ The complete file URL to the video snap (empty when there is no video snap)
$GHOST_VIDEO$ Path to the Ghostbusters logo inside a video frame

DAT info sources:

Macro

Description

$GAME_INFO$ Machine info DB entry (from MAME history.dat / MESS sysinfo.dat) -- note that this macro isn't suitable for use within <script>'s, so if you need to get the data inside a JavaScript section use qmc2NEO.systemInfo() instead
$GAME_INFO_STATUS$ Status of the machine info DB entry (OK / NO_DATA)
$MACHINE_INFO$ Alias for $GAME_INFO$
$MACHINE_INFO_STATUS$ Alias for $GAME_INFO_STATUS$
$EMU_INFO$ Emulator info DB entry (from MAME mameinfo.dat / MESS messinfo.dat) -- note that this macro isn't suitable for use within <script>'s, so if you need to get the data inside a JavaScript section use qmc2NEO.emuInfo() instead
$EMU_INFO_STATUS$ Status of the emulator info DB entry (OK / NO_DATA)

General macros:

Macro

Description

$GUI_LANGUAGE$ The GUI's current language setting (us, de, ...)
$EMULATOR_VARIANT$ The emulator variant (MAME or SDLMAME)
$EMULATOR_TYPE$ The current emulator type (always MAME since v0.52)

See the file data/gmn/template.html as an example template.

Software-notes template macros

Macros for data from the software-list:

Macro

Description

$SOFTWARE_TITLE$ Software's title
$SOFTWARE_NAME$ Software's name / ID
$SOFTWARE_PARENT_ID$ Parent software's name / ID (empty string if there is no parent)
$SOFTWARE_LIST$ Software-list this software is from
$SOFTWARE_PUBLISHER$ Publisher of this software
$SOFTWARE_YEAR$ Year this software was published
$SOFTWARE_SUPPORTED$ Software support status (yes, no or partially / translated)
$SOFTWARE_SUPPORTED_UT$ Software support status (yes, no or partially / untranslated)
$SOFTWARE_INFO$ Software info DB entry (from history.dat), see software information -- note that this macro isn't suitable for use within <script>'s, so if you need to get the data inside a JavaScript section use qmc2NEO.softwareInfo() instead
$SOFTWARE_INFO_STATUS$ Status of the software info DB entry (OK / NO_DATA)
$SOFTWARE_STATUS$ The software-set's status (translated), see software states
$SOFTWARE_STATUS_UT$ The software-set's status (untranslated), see software states

Image macros:

Macro

Description

$SOFTWARE_SNAPSHOT$ Absolute path to the software-snapshot
$GHOST_IMAGE$ Path to the Ghostbusters logo (if an image wasn't found, its file URL will be same as the value of this macro, so you can use it to check image validity)

General macros:

Macro

Description

$GUI_LANGUAGE$ The GUI's current language setting (us, de, ...)
$EMULATOR_VARIANT$ The current emulator variant (MAME or SDLMAME)
$EMULATOR_TYPE$ The current emulator type (always MAME since v0.52)

See the file data/swn/template.html as an example template.

Example templates

For a complete template example which utilizes all the aforementioned features see trunk/data/gmn/template.html in the SVN source tree which is the default template for system-notes.

A less feature-rich example for software-notes can be found in trunk/data/swn/template.html.

Launching emulators

Emulators are started by QMC2 when either an item in one of the machine lists is activated (i.e. when Enter/Return is pressed or an item is double-clicked with the mouse) or a corresponding menu-action is triggered (i.e. Machine -> Play is triggered via the menu).

The way an emulator is launched by QMC2's depends on the mode the GUI is currently in:

  • The default behavior is to spawn a new process for the emulator and start it with command line arguments built from its current configuration, passing the ID of the machine in question.
  • In case one of the Devices or Software lists tabs is the currently in use, the emulator will additionally be passed arguments to mount the specified files or launch the given software.

You'll find detailed information about all emulators launched and controlled by QMC2 in the front-end log:

11:59:18.417: starting emulator #0, command = mame64 -noreadconfig -verbose -skip_gameinfo <...> -nomaximize mario
11:59:18.470: emulator #0 started, PID = 15945, running emulators = 1
11:59:25.422: emulator #0 finished, exit code = 0 (no error), exit status = normal, remaining emulators = 0

On X11 and Windows platforms, QMC2 also allows for embedding of emulator windows. Embedding means that the emulator window will get part of QMC2's UI -- and because that's totally platform-dependent (and slightly hacky), it has some restrictions. However, for the most part it just works:

Embedded emulator

Emulator embedding causes a few more messages in the front-end log:

12:15:41.601: starting emulator #0, command = mame64 -noreadconfig -verbose -skip_gameinfo <...> -nomaximize mario
12:15:41.650: emulator #0 started, PID = 16156, running emulators = 1
12:15:42.062: embedding emulator #0, window ID = 0x2200010
12:15:42.160: emulator #0 embedded, window ID = 0x2200010
12:15:47.379: emulator #0 finished, exit code = 0 (no error), exit status = normal, remaining emulators = 0

Foreign emulators / foreign IDs

This optional view will only be shown -- as part of component (1) -- when at least one foreign emulator has been registered. If custom IDs (used to launch the foreign emulator with the machine/program specified) were set up as well, those will be included as sub-items of the respective foreign emulator.

Foreign emulators view

Both the foreign emulator entries (top-level items) as well as their registered foreign machine/program IDs (sub-items) are launchable, so you can also start the foreign emulator without passing a machine/program on the command line.

For details on setting up foreign emulators, please see the foreign emulator registration section.

Arcade mode

For those who want to go straight into the games there's a new graphical non-desktop mode called QMC2 Arcade which is a QML based approach to presenting an optionally filtered machine list and launching emulators in the same smart way that you're used to with QMC2.

To accomplish that, a Qt/C++ back-end is used which implements all the dirty stuff around emulator configuration, process & settings management, machine list loading, searching items in the machine list and providing related images or emulator-/machine-infos to the QML scene. The Qt/C++ <=> QML/JavaScript interface is mainly property based, but the QML themes can also call certain invokable methods (aka slots) of their controlling Qt/C++ object (TweakedQmlApplicationViewer), which is exposed to QML/JavaScript under the name viewer (detailed information about writing QML themes for QMC2 Arcade can be found on a separate page).

QMC2 Arcade usually loads within just a few seconds and is by far less bloated than the main GUI, trimmed to what's absolutely required -- but although it's designed to run stand-alone, you must start QMC2's main GUI at least once prior to using QMC2 Arcade, because some of the file caches need to be created first (QMC2 Arcade doesn't take care of this itself, which is one of the reasons why it's so much faster). Also, you cannot change the emulator configuration from within QMC2 Arcade. So whenever you want to make modifications to a machine's emulator configuration (or the global emulator setup) you have to do this through QMC2's main GUI.

The main GUI also has a corresponding dialog for setting up all relevant back-end options, for producing a filtered machine list used exclusively by QMC2 Arcade (optional) or to freely map keys/key-sequences and joystick-functions to hard-coded theme-specific key-sequences (also optional):

General settings

Machine list filter

Key-sequence mapper

Joystick-function mapper

For graphics and animations to perform nicely, a decent/modern graphics card and good OpenGL drivers are strongly recommended! So when available, please set graphics system to opengl (OpenGL 2.x and above), opengl1 (OpenGL 1.x) or openvg (OpenVG)! Otherwise keep the default setting of raster (the value native is usually the worst performing one and is thus not recommended, but it should at least work as last resort -- however, depending on the operating system and the graphics sub-system in use, this is often the same as raster effectively).

Command line arguments

Starting QMC2 Arcade doesn't actually require any command line arguments unless you want to use a customized configuration path or overwrite some of the stored settings.

Available CLI options (values enclosed in [..] are the defaults):

Usage: qmc2-arcade [-theme <theme>] [-console <type>] [-graphicssystem <engine>] [-language <lang>]
                   [-video <vdo>] [-config_path <path>] [-fullscreen] [-windowed] [-debugkeys] [-nojoy]
                   [-joy <index>] [-debugjoy] [-h|-?|-help]

Option           Meaning              Possible values ([..] = default)
---------------  -------------------  --------------------------------------------------
-theme           Theme selection      [ToxicWaste], darkone
-console         Console type         [terminal], window, window-minimized, none
-graphicssystem  Graphics engine      raster, native, opengl, opengl1, [opengl2], openvg
-language        Language selection   de, el, es, fr, it, pl, pt, ro, sv, [us]
-video           Video snap support   [on], off
-config_path     Configuration path   [/home/rene/.qmc2], ...
-fullscreen      Full screen display  N/A
-windowed        Windowed display     N/A
-debugkeys       Debug key-mapping    N/A
-nojoy           Disable joystick     N/A
-joy             Use given joystick   SDL joystick index number [0]
-debugjoy        Debug joy-mapping    N/A

(QMC2 0.62+ / QMC2 Arcade 0.25+)

Besides that, you can change the default values for the back-end settings theme, console, graphicssystem, language and video from within QMC2 Arcade itself, provided the chosen theme supports it, or through the arcade mode setup dialog's General settings tab in QMC2's main GUI (see above). The setting for language is a shared setting used by QMC2 Arcade and the main GUI.

Note that changed back-end default options will require a restart of QMC2 Arcade to take effect. Specifying them on the command line will overwrite the current defaults temporarily, but will not change their stored default values.

For Linux/UNIX and Mac OS X, see also the qmc2-arcade man-page.

ToxicWaste theme

Screen shots

Cabinet view (front) Slider settings / manual cabinet zoom & positioning Machine-card (back)

Usage instructions

  • The cabinet image on the left displays the in-game preview image of the currently selected machine from the machine-list, which is displayed in the flickable item-list on the right.
    • Visible machine items can either be mouse-left-clicked to make them the current item, or you can select the current machine by pressing Up, Down, PageUp or PageDown on the keyboard.
    • Pressing End or Home on the keyboard will position the list at its end or beginning, respectively.
    • The list can also be flicked by either dragging it with the mouse or by rolling the mouse-wheel to position the currently displayed content.
    • The up-most visible item is the current item (which is highlighted slightly to indicate this), and the list will always be moved so that the current item is shown in that area.
  • When you mouse-left-click the cabinet's upper/lower or left/right areas to push the cabinet it will flip in the given direction, showing the machine-card on the back-side. Clicking it again will flip back to the front-side (cabinet).
  • The menu-bar in the bottom area of the scene will allow you to search for machines: mouse-left-click into the search-box in the center, then enter the sub-string to search for, optionally including wild-card characters such as * or ?.
    • Every time you press Enter or Return on the keyboard (while the search-box has input focus, indicated by a blinking cursor) or mouse-left-click on the magnifying glass icon left of the search-box, the next matching item (if any) will be made the current item, automatically wrapping around when no more matches follow for the rest of the list.
    • Mouse-left-clicking the icon right of the search-box will clear its text.
  • Mouse-left-clicking the arrow icon in the bottom-left corner will hide/show the menu-bar. When enabled, an FPS counter is displayed next to it (only when the menu-bar is visible).
  • On the right of the menu-bar you'll find click-able icons for opening the preferences dialog, for switching between full-screen and windowed display (also available through pressing Alt+Enter or F11 on the keyboard) and for exiting the application.
  • Pressing Enter or Return on the keyboard (while input focus isn't used otherwise), mouse-left-double-clicking an item in the machine list or mouse-left-clicking the colored machine-start button in the top-left corner of the scene will launch the emulator with the selected machine.
    • The color of the machine-start button will change according to the ROM state of the currently selected machine.
  • The preferences dialog will allow you to change Switches (enable/disable animations and effects, auto-position/-scale cabinet, etc.), Sliders (ranges for manually positioning/scaling the cabinet and for changing some of the opacity settings) and Backend default options, which require a restart of QMC2 Arcade to take effect.
  • Manual vs. automatic cabinet positioning/scaling:
    • When automatic positioning/scaling is deactivated (on the Switches tab of the preferences dialog), you can zoom the cabinet in/out either by using the Cabinet zoom slider on the Sliders tab, or by rolling the mouse-wheel when the pointer is over the cabinet image. Pressing Shift on the keyboard will make it use smaller/smoother zoom in/out steps. Note that the zoom-level is a relative value, that is, some automatic scaling takes place as well depending on the current resolution and aspect ratio.
    • Manual positioning can be done by either using the Cabinet X/Y center offset sliders on the Sliders tab of the preferences dialog, or by pressing Ctrl (Y) and/or Alt (X) and rolling the mouse-wheel up/down at the same time (while the mouse pointer is over the cabinet image). Pressing Shift as well -- together with Ctrl and/or Alt, but after pressing them -- will make it use smaller/smoother positioning steps.
    • Note that the center position changes whenever the resolution changes (as do the available X/Y offset ranges, which also adapt to the current zoom level). So manual positioning/scaling of the cabinet image will most likely only fit for a specific resolution. You will need to adjust it whenever the screen dimensions change.

Notes

  • The ToxicWaste theme makes use of a fragment shader to draw a radial wave-effect on the background. This assumes (and requires) that your OpenGL drivers are "clean and modern" (OpenGL 2.0 is the absolute minimum -- hardware & driver quality may vary, though)!
  • It's recommended that you keep the setting Auto-stop animation and wave effect enabled (see Switches tab in the preferences dialog)! This will effectively cause QMC2 Arcade to use just minimal CPU resources while emulators are running (and you'll notice that by an FPS drop to 0-1, which is actually good rather than a problem here). Of course, you can also disable both the bubble animation and the radial wave effect completely if you like.

darkone theme

Screen shots

Preferences Machine data navigator Cabinet-only view

Usage instructions

  • Zooming is controlled by mouse-wheel-scrolling over (most parts) of the cabinet image, or via the slider control in the preferences menu.
    • Note that zooming is also affected by window resizing.
  • Mouse-left-clicking the cabinet's little machine-start buttons or its grid, or the machine-button on the toolbar, or hitting Return or Enter, will launch the currently selected title (=> note 1).
  • Mouse-double-left-clicking a title on the list will select and launch that title (=> note 1).
  • The toolbar menu auto-hides by default (=> note 2). Position the mouse cursor on the bottom few pixels of the window to unhide it.
  • Mouse-double-left-clicking the arcade screen will reveal the machine data navigator.
    • Navigate images / info by mouse-left-clicking the arrows.
    • Mouse-left-click on the buttons marked 1 or 2 to set the current data item (eg. preview) to be the primary / secondary source of display data.
    • Mixing image and info data types as primary / secondary sources will result in text overlaying the image.
    • Info on the screen is scrollable by mouse-left-down followed by mouse-move (aka flicking), as is the machine list.
  • If the flash effect is enabled, you can hit Escape to immediately back out of the pending machine launch.
  • Hitting Ctrl+Q or mouse-left-clicking the red X in the bottom-right corner of the toolbar menu quits the application.

Note 1: not when the preferences menu is open
Note 2: not when the FPS counter is enabled

Demo mode

A feature originally created for MAME cabinet users is the so called demo mode which will launch random sets from a filtered list of machines in a mode suitable for demo purposes:

Demo mode dialog

Choose the ROM states that machines should have to be included in the demo through the ROM state filter, select the minimum driver status of a set to be eligible for the demo, optionally specify a filter-expression for set-names/-IDs (Qt regular expression syntax, leave empty to not filter by name) and/or restrict the machine categories by selecting / deselecting the ones you want / don't want through the category filter - or alternatively, enable the Tagged option to only pick machines from sets that have been tagged, or the Favorites option to only use machines that are included in the favorites list. Finally, when the Parents switch is activated only parent sets will be included, omitting all clones.

The emulator will basically be launched in the same way (and with the same setup) as it would normally be started in game mode, but for convenience there's a subset of relevant options you can overwrite in demo-mode (Full screen, Maximized and Embedded).

Seconds to run is the time in seconds each emulator will run the emulation; it will exit automatically afterwards -- note that this is not real time but emulation time!

The value of Pause is the (real) time in seconds the demo-mode will pause between each launch of the emulator. This gives you the ability to stop the demo between emulator runs even if using full screen mode (the minimum pause time is one second).

Click the big Run demo button to start the actual demo. After filtering the available sets according to your current filter settings, emulators will be launched randomly - or, if the Sequential option has been set, one after the other, sorted by set-name/-ID in ascending order. The text of the button will change to Stop demo while the demo-mode is active, so clicking it will now stop any running emulator launched in demo-mode and end the automatic emulation launch.

The Close button closes the dialog (as the name suggests) and issues a stop if the demo-mode is currently active.

Configuration

QMC2 has implemented a fairly complex but smart configuration concept based on Qt's QSettings class.

It's capable of saving and restoring nearly any aspect of your local front-end and emulator setup in/from just one ini-file. However, QMC2 also creates a number of cache files and automatically stores all of them below the same configuration path, together with the ini-file (you shouldn't change that, though you can).

Command line arguments

Usage example (for Linux/UNIX and Mac OS X, the binary is called qmc2-mame.exe on Windows):

$ qmc2-sdlmame [-config_path <config_path>] [-cc] [-tc] [-r] [-h|-?|-help] [qt_arguments]

Arguments in detail:

  • -config_path: See configuration path below!
  • -cc: When this CLI option is specified, all emulator caches will be cleared (removed) before the application actually starts up. This is useful whenever the emulator version doesn't change and QMC2 can't figure out that it's time to update the caches because of this (so this mainly applies to those users that are often updating their MAME installation from the public SVN repository).
  • -tc: Specifying this option on the command line will perform a template check against the current default emulator (if set), printing its output to stdout, and exit before actual start-up occurs.
  • -r: The reconfigure option will rerun the setup wizard / welcome dialog before starting. This allows you to update or correct the most important emulator settings in an easy way.
  • -h|-?|-help: Shows a brief command line usage help.
  • qt_arguments: See the QApplication class reference for details on what Qt arguments are available (note, however, that some of these arguments are useless since QMC2 will overwrite them with its saved ini-settings).

For Linux/UNIX and Mac OS X, see also the qmc2 man-page.

Configuration path

When the -config_path command line argument is specified, QMC2 will use this directory instead of its default configuration path, a.k.a. dot-path (see configuration notes below).

Note that whenever you change the dot-path by setting this option, it's in your responsibility to copy/move the data to its desired place prior to starting QMC2, otherwise QMC2 will start over with a fresh and unconfigured setup (which may as well be a wanted behavior, though). Also, any settings that may have inherited the previous dot-path will have to be changed manually (by editing the file <dot-path>/qmc2.ini).

In case you're unsure what the default configuration path (or dot-path) actually is, its value is shown in the command line usage help:

$ qmc2-sdlmame -h
Usage: qmc2-sdlmame [-config_path <config_path>] [-cc] [-tc] [-r] [-h|-?|-help] [qt_arguments]

-config_path    Use specified configuration path (default: /home/rene/.qmc2)
-cc             Clear all emulator caches before starting up
-tc             Check the emulator configuration template and exit
-r              Reconfigure (runs the setup wizard before starting)
-h|-?|-help     Show this help text and exit

Notes on the configuration of QMC2

UNIX and Mac OS X:

  • The user's configuration file will be stored as ~/.qmc2/qmc2.ini on UNIX, or as ~/Library/Application Support/qmc2/qmc2.ini on Mac OS X.
  • A system-wide default configuration can be used to pre-configure any settings for all of your users (common paths: /etc/qmc2/qmc2.ini on UNIX, or /Library/Application Support/qmc2/qmc2.ini on Mac OS X).

Windows:

  • The user's configuration file will be stored as %USERPROFILE%\.qmc2\qmc2.ini on Windows.
  • A system-wide default configuration for all users isn't supported (yet).
  • All paths need to be specified POSIX-like, that is backslashes ("\", Windows) become forward slashes or double back-slashes ("/" or "\\", POSIX) within QMC2 -- so don't be surprised when you see paths like C:/some/directory or C:\\some\\directory (instead of C:\some\directory) in QMC2, because that's how it's supposed to look like! The only exception is the command displayed on the emulator control panel (and in the front-end log) because it may be copied to clipboard and be reused on the command line directly (which wouldn't work with forward slashes on Windows as they are interpreted as argument-separators).

All platforms:

  • If no configuration can be found for a specific option, hard-coded default values will be used for all front end settings (see code Smile :)!); default values for the emulator configuration are read from the current XML template (default paths: /usr/local/share/qmc2/opt/<EMULATOR>/template.xml on UNIX, /Library/Application Support/qmc2/opt/<EMULATOR>/template.xml on Mac OS X, and data\opt\<EMULATOR>\template.xml on Windows).
  • If the path to the emulator's executable file has not been set (yet), QMC2 will assume that you are starting it for the first time (your setup is considered incomplete as long as this option hasn't been set).
  • You can change the file <dot-path>/qmc2.ini manually with any editor at your own risk -- but make sure you only do this when QMC2 is not currently running and take care (i.e. create backups)!
  • The configuration path is also used as the default location for storing a number of cache files. Since reading these files (or databases) has direct impact on the start-up performance, make sure to place it on the fastest media available (i.e. an SSD)!

Configuration backup / restore

Actually, all you need to restore an old QMC2 setup is a copy of its qmc2.ini file!

But in order to avoid useless recreation of the cache files and/or losing your personal user data (i. e. ranks and favorites), we recommend to always backup / restore the complete QMC2 configuration path (or dot-path) by copying or archiving its contents to a safe place.

Following you'll find some examples for the creation of backup-archives from the command line.

Linux / UNIX examples

$ mkdir -p ~/Backup
$ zip -9 -r ~/Backup/qmc2-cfg-backup.zip ~/.qmc2

or

$ mkdir -p ~/Backup
$ tar -czpf ~/Backup/qmc2-cfg-backup.tgz ~/.qmc2

Mac OS X examples

$ mkdir -p ~/Backup
$ zip -9 -r ~/Backup/qmc2-cfg-backup.zip "~/Library/Application Support/qmc2"

or

$ mkdir -p ~/Backup
$ tar -czpf ~/Backup/qmc2-cfg-backup.tgz "~/Library/Application Support/qmc2"

Windows examples

If you're not using some file-browser GUI (like Total Commander) to accomplish that, you can use zip.exe or 7za.exe from the QMC2 installation folder:

c:\QMC2>md c:\Backup
c:\QMC2>zip.exe -9 -r c:\Backup\qmc2-cfg-backup.zip c:\Users\MyUser\.qmc2

or

c:\QMC2>md c:\Backup
c:\QMC2>7za.exe a -r0 c:\Backup\qmc2-cfg-backup.7z c:\Users\MyUser\.qmc2

Front end setup

The following sections try to explain all front-end related settings that can be modified through the main setup dialog (select Tools -> Options from the menu). However, there are also a number of implicit settings and options that are set through their corresponding widgets, which can thus not be customized here.

GUI

GUI settings

Options, meaning and usage:

  • Language: select the GUI's language (this setting requires a restart of QMC2 in order to take effect)
  • GUI style: choose a Qt built-in or plugin style for the GUI
  • Style sheet: select a Qt style-sheet for further theming of the GUI (see compatible Qt style-sheets) -- note that the use of a style-sheet and a modified color-palette (see below) are mutually exclusive, that is you can't (or shouldn't) use both at the same time
  • Application/log font: select the fonts the GUI should use (we recommended to use a mono-spaced font for the logs)
  • Front-end/emulator log size: maximum number of lines kept in the GUI's log widgets
  • Image cache size: maximum size of the (in-memory) image cache
  • Component setup: click this button to setup the order and visibility of all features in all three major GUI components (see the screen shot in the machine-specific detail section - a.k.a. component 2 - for an example)
  • Tool-bar: this button opens the (pretty much self-explanatory) tool-bar customization dialog
  • Scaled preview/flyer/etc.: scale all images to fit the widget size (or use original image sizes)?
  • Smooth scaling: scale images smoothly (a bit slower, but nicer)?
  • Retry loading images: try reloading images that weren't found before (while that information is still cached)?
  • Parent image / video fallback: fall back to images, icons or videos from parent sets (if any) when individual images/icons/videos for clone sets aren't available?
  • Individual fallback settings: click this button to open the individual fallback settings dialog that lets you customize parent fallback settings individually per artwork class:
Individual parent fallback settings
  • Default palette: allows the use of a customized color-palette when disabled by clicking the Edit color palette button that's then available:
Palette editor

QMC2 switches back to the default palette of the current style when this option is enabled.

Note that the use of a style-sheet (see above) and a modified color-palette are mutually exclusive, that is you can't (or shouldn't) use both at the same time.

  • Show status/tool/menu bar: display or hide any of the status-, tool- or menu-bars
  • Show progress texts: show small texts in the main progress-bar indicating the current activity?
  • Minimize on emulator launch: minimize (iconify) all front-end windows when launching an emulator, restoring them automatically when the emulator exits
  • Use native file dialogs: Use the system's own (native) file dialogs when enabled and available, otherwise use Qt's built-in ones (which is the default and generally recommended)
  • Check single instance: check if another instance of QMC2 is already running when starting up?
  • Machine status indicator (only when required): show a colored indicator of the currently selected machine's ROM status (do this always or only when required)?
  • Show machine name (only when required): render machine names as overlay texts into all images (do this always or only when required)?
  • Suppress Qt messages: suppress all messages generated by Qt itself (not recommended since they may indicate erratic behavior)?
  • Show splash screen: show the splash screen when starting up?
  • Show loading animation: show an animation whenever the machine list is reloaded, filtered or tagged/untagged?
  • One emulator at a time: terminate all running emulator instances when launching a new one
  • Kill emulators on exit: kill emulators when exiting QMC2 or leave them up and running?
  • Set working directory from executable: when this option is set, QMC2 will change its run-time working directory to the path where the running executable is stored -- this may be useful if you want to use relative paths elsewhere in the configuration (i. e. for portable setups).

Files and directories

File and directory settings (front-end related)

Options, meaning and usage:

  • Front end log file: path to the front-end log file
  • Favorites file: path to the file used to store your favorite machines
  • Play history file: path to the file used to store your personal play history
  • Data directory: path where QMC2's (static) data files are installed (usually predefined by the install mechanism)
  • DAT-info database file: SQLite 3 database file used as the combined data-store for all DAT-info sources:
    • Machine info: file used as input for the machine information database (automatically re-imported to the DAT-info DB every time the file changes) -- there are two separate options for MAME (history.dat) and MESS (sysinfo.dat) in order to allow for merging them
    • Emu info: file used as input for the emulator information database (automatically re-imported to the DAT-info DB every time the file changes) -- there are two separate options for MAME (mameinfo.dat) and MESS (messinfo.dat) in order to allow for merging them
    • Software info: file used as input for the software information database (automatically re-imported to the DAT-info DB every time the file changes)

  • Use catver.ini: when this option is enabled and the path to catver.ini has been specified, QMC2 will activate two additional machine list views (by category and by version); any modification of this setting will trigger an automatic reload of the machine list - clicking the speed-indicator button will open the catver.ini optimizer which can be used to potentially speed up loading slightly:
Catver.ini optimizer in action
  • Use category.ini: when this option is enabled and the path to category.ini has been specified, QMC2 will activate an additional view (by category), merged with the category-data from catver.ini when both info-sources are specified; any modification of this setting will trigger an automatic reload of the machine list
  • Preview/flyer/icon/etc. file/directory: click on the radio buttons to switch between file-based (ZIP-/7z-archive) or directory-based loading of any machine images, and select the file or directory to be used
    • Note that you can also specify multiple folders (or ZIP/7z archives) per image category -- use semicolon (;) to separate them!
    • For best performance, we recommend to use directory-based storage for all image-types except icons, which should be stored file-based (ZIP-/7z-archive) -- please read this FAQ for more details.
    • If your build includes support for libarchive you'll see three alternative methods to read archives: ZIP (built-in), 7z (built-in) and Archive (external). Support for libarchive is optional.
    • Since v0.70, icons will be imported to the so called icon cache database (once or on demand) in order to speed up loading them. There's a simple setup dialog for the icon cache database which you can reach by clicking the tool-button right of its label (disabling the database will fall back to pre-0.70 behavior):
Icon cache database setup

  • Set up additional artwork classes: clicking this button will open the additional artwork classes dialog that enables you to define your own custom artwork (image) classes to be used throughout QMC2. Just as with built-in artwork classes you have the choice between folder- or archive-based storage of images (per class), selected in the type column. The artwork name must be unique within all custom artwork classes. If it contains an ampersand (&) as in the examples below, the character after it will automatically be used for the accelerator key-sequence (Alt+<Character>), but this is optional. Also optional is the selection of an image file used as the icon for this artwork class. The target defines if it's used with systems (machines) or software:
Defining additional artwork classes

Note that you need to activate (or deactivate) custom artwork classes - just like any other machine- or software-detail - via the component setup! You'll find artwork for systems as part of component (2) and artwork for software as part of component (4). When you remove an actively used artwork class it will also be removed from the respective component.

Note also that using ampersands can help making artwork names unique when they are used for similar types of assets - for example, using "&High score" for systems and "High score" for software would work fine.

  • Select image formats: click this button to open the image format setup dialog which will allow you to activate/deactivate support for any of the available image file formats and to change their priorities. The up-most activated format is the one which is used first when a corresponding image file exists and can be loaded successfully, otherwise the next activated format will be used, if available. This may continue until the last active format has been reached, so it can hurt performance if you overdo or do it wrongly. Only activate the formats that you really need and prioritize them wisely (for instance, if you have just a few JPG images and many PNGs for a certain artwork class, it's obviously better to prefer PNGs over JPGs). Use drag & drop to move the format items (list-internally) in order to change their priorities. Note that when all image formats are deactivated, PNG will be the default format that's reactivated automatically. All these settings are individual per artwork class (select it through the combo-box in the bottom-right corner of the dialog):
Image format setup
  • System notes folder: the base-folder used for personal rich-text (HTML) notes about each system (contains the actual HTML files named as the systems they represent -- all of this will only be created when it's absolutely required, though)
  • System notes template: if you want your system-notes to all look quite similar (i.e. common header information, common sections) and don't want to edit this information over and over again, you can just enable this feature and point QMC2 to the actual template file; QMC2 comes with a sample template which you can use right away and/or edit to your needs (the available placeholder macros are explained in the system-notes templates section) -- note that when a template is used, individual HTML system-notes will only be stored when the actual data differs from what the template creates; if templates are not used, notes will be stored when they differ from a null-page
  • Software notes folder: the base-folder used for personal rich-text (HTML) notes about each software listed in software-lists (sub-directories named as the software-lists will be created on-demand, containing the actual HTML files named as the software-list entries they represent -- all of this will only be created when it's absolutely required, though)
  • Software notes template: if you want your software-notes to all look quite similar (i.e. common header information, common sections) and don't want to edit this information over and over again, you can just enable this feature and point QMC2 to the actual template file; QMC2 comes with a sample template which you can use right away and/or edit to your needs (the available placeholder macros are explained in the software-notes templates section) -- note that when a template is used, individual HTML software-notes will only be stored when the actual data differs from what the template creates; if templates are not used, notes will be stored when they differ from a null-page
  • Video snap folder: video snaps (previews) for systems are stored in this directory. You can specify multiple folders by separating them with semicolon (;).
  • System/Software manual folder: these directories are the places for storing system- or software-manuals, respectively. Valid paths for system manuals must be named as <system-manual-folder>/<system-name>.pdf, valid paths for software manuals have to be in the form <software-manual-folder>/<software-list>/<software-name>.pdf. You can specify multiple folders by separating them with semicolon (;). Fallback to a parent's PDF manual is done automatically if there's no document for a clone-machine or -software.
    • Note that after applying the settings (saving the manual folder(s)) you also have to scan for system- and/or software-manuals explicitly - click one of the tool-buttons left of the folder-inputs to open the scanner:
PDF manual scanner

Machine- / Software-lists

Machine list settings

Options, meaning and usage:

  • Common settings
    • Double-click activation: should a double-click with the pointer (usually mouse) launch an entry?
    • Play on sub-list activation: when a machine item is activated on a sub-list (search-, favorites- or played-lists), should QMC2 play (launch) it or jump to the machine list? (the latter is the default behavior when this is disabled)
    • Cursor position: this option specifies where the cursor will be positioned in any list when QMC2 has to scroll it to make the current item visible
    • Default launch mode: on systems where emulator embedding is supported (X11 and Windows right now), select the default launch mode (embedded or independent) used when starting an emulator by activating an item from any list, i. e. by double-clicking an entry; the default launch mode will also be used when starting foreign emulators with custom IDs through the menu
    • Update delay: number of milliseconds to delay detail updates after selecting an entry; you can disable this by choosing 0 (= immediatly), but it's not recommended, especially not on older hardware
  • Machine lists
    • Show BIOS sets: include BIOS sets in machine lists? (if not, they will be hidden and can still be searched)
    • Show device sets: include pure device sets in machine lists? (if not, they will be hidden and can still be searched)
    • Show ROM status icons: display or hide icons indicating the ROM status of a machine (or BIOS set or device); toggling this option will trigger an automatic reload of the machine list in order to take effect
    • Auto-trigger ROM check: should a full-audit ROM check be triggered automatically when QMC2 finds out that the version of the emulator has changed or the number of supported sets is different than the number of cached ROM states?
    • ROM state filter: toggle ROM state filtering and/or select ROM states to be shown or hidden by the filter-mechanism
    • Sort criteria/order: select the criteria and order used when sorting all machine list views
    • Responsiveness: number of consecutive list insertions before doing any GUI updates when loading the machine list (this had major impact on performance in earlier days, but is more or less irrelevant nowadays, so we recommend to just keep the default!)
    • Save/restore machine selection: save and/or restore the last selected machine (on every reload)
  • Software lists
    • No SW snaps for visible details: automatically hide software-snaps when the software-detail widget is active? (it may be annoying and useless to have both activated at the same time since the SW-detail already includes a full-featured snapshot viewer)
    • Software snaps on mouse hover: should hovering the mouse cursor over a software-list activate the display of any available software-snapshots? (otherwise software-snapshots will only be displayed when a software-list entry has been selected)
    • SW snap position: select where software-snapshots (in software-lists) are to be displayed, relative to the corresponding entry
    • Save/restore software selection: save and/or restore the last selected software (per system)

Shortcut keys

Defining/scanning shortcut-keys

Usage description:

  • Redefine key sequence: click this button for a selected function or key (or double-click on an entry) to redefine the key-sequence used to simulate that action or special-key
  • Reset: reset a customized key-sequence to its default
  • Note the color-indication (red/green) and check for any conflicts! (conflicts will also be logged to the front-end log)

Joystick setup

Joystick control setup

Options, meaning and usage:

  • Enable joystick control: this will enable (or disable) GUI control via a digital joystick in addition to the usual keyboard- and mouse-control
  • Rescan joysticks: rescan the available joysticks plugged in / pulled out at run-time
  • Select joystick: choose the joystick device used for GUI control (when there's only one joystick, it will be auto-selected)
  • Auto repeat after: every joystick function can be repeated automatically, just like any pressed and hold key, and you can control after how many milliseconds QMC2 should start auto-repetition
  • Event timeout: this parameter can be used to change the polling interval used to check for joystick events
  • Calibrate: calibration means to move all axes to their positive and negative maximums so QMC2 knows their ranges
  • Test: test the functionality of the selected joystick's axes, buttons, hats and/or trackballs
  • Map: map joystick functions (axes movement, button presses, ...) to GUI control keys, special keys and/or directly connected actions
  • Remap: opens a joystick function scanner dialog to redefine the currently selected entry
  • Remove: removes and disables the selected mapping (if one was made previously)

Network and tools

Network and tool settings

Options, meaning and usage:

  • Use HTTP proxy: enable this if you need (or want) to use an HTTP proxy for any of QMC2's built-in web-browsers
    • Host / IP: the proxy's host name or IP address
    • Port: the port used to contact the proxy server
    • User ID: if proxy-authentication is required, enter your user ID here (if not, leave empty)
    • Password: if proxy-authentication is required, enter your password here (if not, leave empty) -- note that the password is stored locally, not in clear text, but the encryption that's used is considered weak
  • Browser settings
    • Restore cookies: when this option is activated, QMC2 will store cookies in an SQLite database on exit and load them during start-up
    • Manage store cookies: clicking this button will open a simple table-view that you can use to show and/or remove individual cookies that are currently stored in the DB -- note that cookies will only be stored when QMC2 exits, otherwise they are held & managed in memory, so new cookies created during the current session will not show up here
    • Clear database: click this button to clear the cookie DB (by recreating it)
    • Cookie database: the SQLite database file used for the cookie DB
  • Zip tool
    • Command: the external command (or path to its executable) used to remove a set of (obsolete or bad) files from ZIP-archived image- or icon-collections (never automatically, only when requested by the user) -- note that the command must be capable of removing multiple files from a ZIP-archive at once
    • Arguments: argument list passed to the zip tool to remove files from an archive -- valid placeholder macros are $ARCHIVE$ and $FILELIST$, replaced at run-time with the currently processed ZIP archive's absolute file path ($ARCHIVE$) and the space-separated list of files to be removed ($FILELIST$)
  • 7-zip tool
    • Command: the external command (or path to its executable) used to remove a set of (obsolete or bad) files from 7z-archived image- or icon-collections (never automatically, only when requested by the user) -- note that the command must be capable of removing multiple files from a 7z-archive at once
    • Arguments: argument list passed to the 7-zip tool to remove files from an archive -- valid placeholder macros are $ARCHIVE$ and $FILELIST$, replaced at run-time with the currently processed 7z archive's absolute file path ($ARCHIVE$) and the space-separated list of files to be removed ($FILELIST$)
  • ROM tool
    • Command: the command (or path to its executable) used as a generic tool for any external processing based on the machine's ID and/or its description -- it's completely up to you what this tool might do, ideally though, it should have some sort of ROM management functionality :)
    • Working directory: the working directory used for the execution environment of the external ROM tool (if empty, QMC2's current working directory is used)
    • Arguments: argument list passed to the ROM-tool -- valid placeholder macros are $ID$ and $DESCRIPTION$, replaced at run-time with the ID of the currently processed machine ($ID$) and/or its description ($DESCRIPTION$)
  • Copy tool output to front end log: when this option is enabled, all output generated from running an external tool will be copied to the front-end log (i.e. to keep it for debugging)
  • Close dialog automatically: when an external tool is run, a modal tool-executor dialog will pop up, and this option decides if the dialog should be kept open until you dismiss it or be closed automatically when the command has finished

For details regarding external tools and the expected tool argument syntax please see section 7 in the README.

Emulator setup

All important configuration aspects for QMC2's default emulator as well as (optional) foreign ones can be set up through the Emulator tab on the main configuration dialog (choose Tools -> Options from the menu, then select the Emulator tab).

The default emulator is the one that's the main source for all sorts of information displayed and handled by QMC2, and it must therefore be in the set of supported emulators. The configuration of these emulators can be fully controlled by QMC2 since it knows all of their command line switches / ini-settings, and it also knows about their peculiarities and ways to circumvent them in order to handle them correctly.

Foreign emulators, in contrary, are completely unknown to QMC2 and thus require the user to register them before they can be used. However, the support for foreign emulators (a.k.a. additional emulators) should be generic and flexible enough to make most, if not all, of them work through QMC2.

Note that the machine IDs used throughout the front-end are all based on the default emulator. So if a foreign emulator doesn't use the same IDs, you'll also have to supply QMC2 with those if you want to launch its machines.

Global configuration

Global emulator configuration

Usage description:

  • All global settings of the current default emulator that QMC2 knows about (through the active configuration template) can be customized on this page.
  • As long as no changes were made by the user, QMC2 chooses exactly the same default configuration settings that the respective emulator would use (without a front-end) when it hasn't been explicitly configured. That is, QMC2 passes only those settings to the emulator which have different values than their default values (again, as read from the active configuration template).
  • The interface of the global emulator set up works in the exact same way as the machine-specific configuration, so please refer to this section for more details. The main difference between the two is that global settings can be seen as a customized default configuration, whereas local settings can be used to overwrite them for individual machines.
  • It's strongly recommended that you read this FAQ for a better understanding of how QMC2 configures emulators. It also explains the different configuration scenarios you could flexibly choose from in case you want to set up things your own way.
  • Note that there's a function to check for obvious differences between the active configuration template and the currently selected default emulator. In case you're missing something, please run it and send us the resulting log output (see Tools -> Clean up -> Check template map):
13:06:53.294: checking template configuration map against selected emulator
13:06:53.371: done (checking template configuration map against selected emulator)
13:06:53.372: check results: 0 differences

Files and directories

File and directory settings (emulator related)

Options, meaning and usage:

  • Executable file: this is the path to the default emulator's executable file (or binary) -- changing this option on-the-fly will trigger a reload of the entire machine-list (as soon as you apply your changes)
  • Working directory: the working directory that's used whenever the emulator is launched in play or demo mode; if unset (= empty), QMC2's current working directory will be used (whatever that might be)
  • Emulator log file: the file that's used to store every output produced by the emulator when launched in play or demo mode -- this file will be truncated (cleared) whenever QNC2 is restarted and the emulator is launched at least once
  • Options template file: the path to the XML file representing the emulator configuration template used as the rule-base for the configuration of the emulator (which should thus be 100% correct / up-to-date) -- when you've changed it, for instance to select a customized template, either restart QMC2 or select Tools -> Clean up -> Recreate template map from the menu in order to refresh this information
  • XML cache database: this SQLite 3 database is used to cache the emulator's full XML data (output from -listxml) in order to quickly retrieve that information later / on demand
  • User data database: machine related additional information like personal ranks (supported by QMC2's ranking system) and comments (for future use) are stored in / retrieved from this SQLite 3 database
    • The button right of the file name edit can be used to clear / initialize the database (all data will be removed!) -- you'd have to confirm this on a follow up safety question, though.
    • The broom button right of the clear button will remove obsolete entries (entries for machine/device names that no longer exist) and ones where no data is available (no rank / no comment).
  • Machine list cache: all information that's available in QMC2's machine lists is cached in this file to speed up the load process (this does not include the detailed machine information, which will be retrieved on demand)
  • ROM state cache: ROM status / audit information gathered while checking ROMs will be stored in this cache file so you don't need to recheck ROMs every time -- note that you have to check the ROMs of at least one machine to create this file, or select Tools -> Check ROMs from the menu to trigger a full audit
  • Slot info cache: slot information output from the -listslots emulator command will be cached in this file to speed up subsequent reading of the same data
  • Software list cache DB: software-list data that's collected through the -listsoftware command will be cached in this SQLite 3 database to speed up loading of software-lists
  • Software state cache: when software-state checking is enabled, individual state cache files (*.ssc) for each software-list will be stored in the directory specified here
  • General software folder: whenever software is to be loaded outside of software-lists (i.e. through the file-chooser), this directory will be used as the starting point to search for software; if this directory contains a folder that's named like the current machine's ID (or short-name), QMC2 will automatically choose this sub-folder instead -- note that you can explicitly specify a software-folder for each machine (in the respective dialogs), in which case the general software folder setting will be ignored
  • Automatically recreate all emulator caches when the output from '-listfull' changes: it does what it says :), and we recommend that you keep it enabled (note that changes to devices and software-lists aren't recognized automatically, though)
  • Skip emulator identification when the file's modification time hasn't changed: this should be pretty self-explanatory :). As long as you don't fiddle with the modification times of the emulator executable file(s) on disk this should speed up loading nicely (and is therefore enabled by default)

Additional (foreign) emulators

Setting up additional (foreign) emulators

Usage description:

  • To register a new foreign emulator, enter its unique name (which identifies the emulator throughout QMC2) into Emulator name, specify the required path to its Executable file, the optional Working directory and the command line Arguments used when launching it. Then click on the Add button to add the emulator to the list in the upper area.
    • You can optionally change the icon used for a registered emulator by clicking the left-most tool-button (showing the current icon). Press and hold the button to open its attached menu which contains an action to reset the icon to the default alien icon (or no icon at all).
  • Note that the previous step alone doesn't activate (nor save) the newly registered emulator(s) -- you have to click Apply (or Ok) for changes to take effect!
  • When you click on an entry in the list of registered emulators, the input fields below the list will be filled with its data which you can edit/replace whenever needed (again, apply your changes to take effect).
  • Foreign emulators that use different machine IDs than what the default emulator (MAME) uses will require you to specify their foreign IDs as well. To do so, click on the "Custom IDs..." tool-button (right-most column) and edit the IDs & descriptions in the dialog that's popping up (as shown in the screen shot above).
    • As with the foreign emulators they belong to, you can optionally specify individual icons per custom ID by clicking the left-most tool-button (showing the current icon). Press and hold the button to open its attached menu which contains an action to reset the icon to the default Pac-Man icon (or no icon at all).
  • Note the two placeholder macros $ID$ and $DESCRIPTION$: $ID$ will be replaced with the current (or custom) ID of the machine, $DESCRIPTION$ will be replaced with the current (or custom) description/title of it. This is done for command-line arguments when the emulator is launched as well as for entries of the Foreign emulators view. The view is dynamically created / updated whenever foreign IDs are modified and the settings are applied.
  • The Display format combo-box lets you choose the way foreign ID entries are displayed in the Foreign emulators view.
  • You can copy foreign IDs from one emulator to another which should make your life easier in many cases (see Copy IDs menu button).
  • Take care to include the $ID$ placeholder at the correct place within the command line arguments! At the very least it won't work correctly if $ID$ is omitted, which is why the existence of the $ID$ placeholder is indicated in green (probably OK) or yellow (probably NOT OK).
    • However, note that when you launch a foreign emulator directly, that is without passing it a foreign ID, both the $ID$ and $DESCRIPTION$ placeholders will be replaced with empty strings. So if you intend to launch foreign emulators directly as well, choose a command line / custom ID combination that would work in both cases. Otherwise just register an additional foreign emulator with modified arguments, probably omitting $ID$ completely (you can ignore the missing $ID$ warning indication in this case, of course).

Notes:

  • Foreign emulators are seen as aliens by QMC2, which basically means that it has not much control over them, and there may be situations we'll never be able to support (we're not aware of any yet, though). Also, embedding of foreign emulators will most likely only work if they are close enough to current MAME (i.e. derived from them or just slightly older versions).

ROM- and software-states

Every single machine (or set/system) has a ROM state in QMC2 which represents the set's verification status from MAME (determined through the emulator's -verifyroms command). Same basically holds for known software contained in software-lists, this time called software-states (determined through the emulator's -verifysoftlist command).

Checking ROM-states

Since the process of checking all ROMs may be a very time-consuming task (depending greatly on the number of supported sets, the available files in your ROM path(s) and the overall system performance), QMC2 does not trigger this automatically unless explicitly told to do so. So don't be surprised that the ROM states of all sets are unknown in the first place, which is indicated through the blue sphere icon shown in front of the title of each item.

A full audit to check the complete collection can be triggered through the Tools menu (select Check ROMs). When a -- presumably valid -- ROM state cache already exists, you'll be warned that this process may take long and all cached ROM state information will be recreated. This is just a safety measure in case you've unintentionally hit the check ROMs action (i.e. via its tool-bar icon).

Note that QMC2 also allows for checking ROM states of individual sets (or a collection of tagged sets). This is especially useful when just a few ROMs were updated and a full audit is thus not really required.

Whenever ROM states are checked, QMC2 stores this information for later use in its so called ROM state cache file. Every time ROM state information changes -- either after an audit or when loaded from cache -- a short state info message is written to the front-end log (example for using a valid ROM state cache):

12:09:27.411: loading ROM state from cache
12:09:27.450: done (loading ROM state from cache, elapsed time = 00:00.038)
12:09:27.453: 2620 cached ROM states loaded
...
12:09:28.039: 1772 machines, 0 BIOS sets and 848 devices loaded
12:09:28.039: ROM state info: L:2620 C:2091 M:529 I:0 N:0 U:0

You can also instruct QMC2 to automatically check ROM states whenever it considers the state-cache to be out-of-date (see the auto-trigger ROM check option on the setup dialog's machine list page) which will be triggered when the ROM state cache file can't be found or is invalid, when the number of supported sets differs the number of cached states or when at least one system's ROM state is unknown (and that information isn't contained in the cache itself). Here's a log excerpt for this kind of setup (MAME example, after clearing the ROM state cache):

12:05:07.131: 28560 machines, 67 BIOS sets and 34 devices loaded
12:05:07.131: ROM state info: L:28661 C:? M:? I:? N:? U:28661
12:05:07.133: WARNING: ROM state cache is incomplete or not up to date, triggering an automatic ROM check
...
12:05:07.388: verifying ROM status for all sets
12:05:51.731: checking real status of 13 sets not mentioned during full audit
12:05:58.923: done (checking real status of 13 sets not mentioned during full audit)
12:05:58.932: done (verifying ROM status for all sets, elapsed time = 00:51.544)
12:05:58.932: ROM state info: L:28661 C:25748 M:2911 I:2 N:0 U:0

Checking software-states

Like with the ROM states for machines, state information for software-sets isn't checked automatically. You have to enable it explicitly and trigger check software-states (see this section) for each software-list to get state information displayed as colored icons. When software-states haven't been checked yet their software's states default to unknown.

State information gathered during software-list audits will be cached as individual state cache files (*.ssc) in the software state cache folder specified on this tab of the main setup dialog. Every time state-information for a software-list changes -- either after an audit or when loaded from cache -- a short state info message gets written to the front-end log:

12:47:00.425: state info for software-list 'neogeo': L:240 C:164 M:0 I:76 N:0 U:0

Meaning of ROM- and software-states

Machine list statistics are shown in the lower-left corner of the main widget, below the machine list. Similarly, combined statistics for all software-lists supported by a system are shown below the software-list widget. All letters (and their colors) have the meanings as shown in the table below. These letters are also used for all ROM- or software-state infos written to the front-end log.

State letter

State name

State color

State icon

State meaning

C correct green Icon for ROM state 'correct' / Icon for SW state 'correct' Correct: All dumps exist emulator-wise; they also exist in your local collection, and their header check-sums are the expected ones. The machine or software will most likely work fine (provided its driver is mature enough).
M mostly correct yellow green Icon for ROM state 'mostly correct' / Icon for SW state 'mostly correct' Mostly correct: One or more dumps are missing or bad (emulator-wise), but your collection has all (correct) dumps that are available. The machine or software may not work (as expected), but most of the time it will run fine (provided its driver is mature enough).
I incorrect red Icon for ROM state 'incorrect' / Icon for SW state 'incorrect' Incorrect: One or more dumps in your collection are bad (there may also be missing or bad dumps emulator-wise). The machine or software may not work, and most of the time it won't.
N not found gray Icon for ROM state 'not found' / Icon for SW state 'not found' Not found: One or more required dumps are missing in your collection (there may also be missing or bad dumps emulator-wise). The machine or software will not work.
U unknown blue Icon for ROM state 'unknown' / Icon for SW state 'unknown' Unknown: The ROM-/software-state of the respective machine or software hasn't been checked yet (or something went wrong during the check, or the check was prematurely interrupted).

Individual states are displayed in the machine- or software-list itself, indicated by the icons shown above. In case of BIOS sets the icons contain a white B, and state-icons for device sets contain a white D.

Note that with regard to ROM states there are also less obvious situations. One of them is discussed in this FAQ (referenced devices). Another one is that some ROM dumps are marked as optional. This has no impact on the ROM states, but the ROMAlyzer can help identifying those situations.

Checking samples

Sample-checker dialog

Clicking check samples will trigger a new sample-check. The button's icon and text will change accordingly (stop check), so its second role is to stop the sample-checker when it's active.

As a preparation for the actual sample-check, QMC2 will first parse and analyze the emulator's XML data in order to identify which individual samples are required (many samples are shared between sets, so it makes sense to only check those who carry the parent samples). When QMC2 finds any relevant bugs with regard to the emulator's sample-related XML output, it will log corresponding warnings in the front-end log.

In a second step, the status of each unique identified sample will be verified (by means of the emulator's -verifysamples command).

The final check will search for obsolete files and/or folders within any of the sample-paths. If QMC2 finds at least one, the tool-button to remove obsolete files / folders (above the list of obsolete items) will be enabled. Triggering it will remove all obsolete files / folders it found, so be careful!

In the ideal case, you should see something like this in the log:

16:34:49.411: verifying samples
16:34:49.413: preparing sample-check: parsing XML data for relevant sample information
16:34:58.885: found 75 individual sample sets and 264 systems using samples
16:34:58.887: check pass 1: checking sample status
16:35:02.759: check pass 2: checking for obsolete files / folders
16:35:02.761: done (verifying samples, elapsed time = 00:13.349)
16:35:02.762: 75 good, 0 bad, 0 missing, 0 obsolete

Checking your image collection

QMC2 includes a built-in tool -- the image checker -- which supports you in the fight for keeping your image- and icon-collections clean and up-to-date.

Select the image type to be checked, the number of threads used when checking images (icon checks are not multi-threaded), and then click the green Start/Stop button on the right to start the scan:

Image checker GUI

You can switch to the log at any time, but scans are usually faster when you only do this after the scan is complete:

Image checker log

Note that scans can be interrupted at any time by clicking the (now red) Start/Stop button again.

When the check-able tool-button right of the thread number is checked (active), machine items from the master list will be selected whenever an item in the found- or missing-list is selected.

Right of the Start/Stop button you'll find two buttons to clear all lists and the log (gives memory back when the dialog is no longer used) and to save the log's current contents to a local file.

When bad (corrupt) image files were found during the check, they will be contained in the missing list -- QMC2 cannot use them, so they are are also classified as missing internally. However, the image checker will symbolize bad files explicitly with a warning icon in front of them, and the bad-counter will be set accordingly in this case (also check the log for image-reader errors). The bad-count is placed on a toggle-button above the missing list, and it will trigger a filtering of the missing-list to only show the bad ones when it's activated (or to show all missing images when it's deactivated). Use the remove bad image files button next to it in order to remove the corrupt files.

And finally, there's a button above the obsolete list to remove files that couldn't be mapped to any machine and are thus obsolete.

Notes:

  • When image- or icon-files are stored directory-based, the removal of any files will be done with Qt built-in functionality. In case of zipped or 7-zipped images / icons the removal is done through the external zip or 7-zip tool.
  • Testing for bad icons is currently not possible, so the bad-counter / bad-file-removal buttons will be hidden when icons are checked.

Analyzing sets with the ROMAlyzer

In contrast to the ROM or software check features, which basically tell us what the emulator thinks about the state of the available dumps (this is actually just a cursory inspection since it only checks against header check-sums, and it doesn't reveal much detail on what's up with individual dumps or which files it actually tries to use), QMC2's ROMAlyzer takes a much deeper look into each ROM and/or CHD file contained in one or more sets, and reveals that through its user interface. It's designed to be run in batch mode (i.e. for analyzing the complete collection, or parts of it) as well as for individual checks.

As of version 0.52 the ROMAlyzer has evolved to a full-featured ROM management tool, and although we're not aiming to compete with other existing tools like clrmamepro (cmpro) or RomCenter it's meanwhile quite feasible to manage your ROM- and software-collections with QMC2's ROMAlyzer. The most important advantage of QMC2's ROMAlyzer compared to the other tools probably is that it's platform-independent.

There are two separate instances of the ROMAlyzer running in different modes, one for systems and one for software (or software-lists). The ROMAlyzer's software-mode basically acts the same way as its system-mode pendant, additionally honoring the software-list a set belongs to. Since they are so similar, the following sections will only describe the ROMAlyzer's system-mode. Just keep in mind that there's equivalent functionality for software / software-lists. However, note that certain features are named differently in software-mode (and some system-mode specific functions aren't available at all).

General usage

To utilize the ROMAlyzer, specify one or more sets to be analyzed as a list of space-separated match patterns and click Analyze. Alternatively, you can use the respective items in the system or software context-menus to initiate the analysis of the currently selected set. There's also a menu action for analyzing all tagged sets in a row (see Machine -> Check -> Analyze ROMs (tagged) in the main menu).

ROMAlyzer report

Each match pattern can be a short name of a set (the set's ID) or any combination of characters and wildcards (see Qt's wildcard-matching for details) to specify a filter for sets to be included. For instance, if you'd like to run the ROMAlyzer over the complete collection just enter *, or in case you'd want to check all sets that start with a digit you could use [0-9]* to accomplish that.

Here are some more or less unsorted facts on what the ROMAlyzer does to analyze sets, and how it's performed (including usage information and recommendations where applicable):

  • The ROMAlyzer imitates the emulator's way of finding ROMs, using their CRCs to identify the individual dumps which are stored in ZIP- or 7z-archives (the CRCs are looked up in the archive's header/directory structure).
    • ZIP- and 7z-archived ROMs will be loaded (decompressed) and their check-sums will be recalculated on-the-fly which will also identify any archive integrity issues (i.e. a header check-sum doesn't match the real check-sum of an archive's member).
  • ROMs which are stored as regular files in folders named as the corresponding machines will also be loaded to calculate their check-sums (only in this case - and for CHDs which are regular files per definition - the file names really matter).
  • The ROMAlyzer uses the XML data to compare expected check-sums and sizes against the calculated ones. It also gathers all information about required/optional ROM & CHD dumps, if they need to / can be merged from other sets etc. pp. from the XML data.
  • All required hash algorithms are supported: CRC(-32), SHA-1 and MD5 (note that MD5 check-sums are no longer included in the emulator's XML data, so you should disable their calculation in the ROMAlyzer settings; it's only there for backward-compatibility and disabled per default).
  • CHD verification is accomplished through the comparison of the header check-sums (stored in the CHD) with the expected hash values (from the XML data); you can optionally enable deeper file integrity verifications through the CHD manager (chdman) which is thus required to use this feature (can be slow).
    • The CHD manager will allow you to optionally update your CHDs on-the-fly if applicable -- please backup your CHDs before enabling automatic updates! Also, make absolutely sure you're using the latest version of chdman, that is, the version that came with your current MAME release. QMC2 assumes that CHD version 5 is the latest and greatest format, and it will only try to update a CHD if its version is less than that.
    • For best performance, choose a temporary working directory for the CHD manager which is on the same file system as the CHDs you're analyzing! The reason for this is that in the final step we simply rename/move the updated chdman's output to replace the old CHD. If it's on the same file system, the update will just change the meta-data (and will not have to move the real data).
    • If QMC2 is unable to replace an updated CHD (for instance due to missing write permission on the ROM path) it will keep the updated file in the CHD manager's temporary working directory and you'll need to copy/move it manually.
  • ROM and CHD files will never be fully loaded into memory while analyzing, only small blocks of data are read for hash calculation and dropped directly after use. However, the set rewriter will load all uncompressed data of a set into memory -- so if you're planning to use this feature, a system with at least 4 GB of RAM is recommended (it actually only depends on the largest ROM set available in MAME, not counting any CHDs here).
  • Long ROMAlyzer runs can be paused / resumed or interrupted at nearly any time. Except when a set is currently being rewritten, interruptions take place immediately, and a running external chdman-process will be terminated.
    • Pausing the analysis is nicer and takes place asynchronously, waiting for the current set to finish its analysis. You can then still stop the analysis if you like.
  • ROM sets that use merged files will also be checked for their merge-states. Possible states include:
    • Merge status OK (OK): All merged files are at their expected places and are taken from the parent set.
    • Merge status WARNING (WARNING): One or more files to be merged are taken from the child set, but if the parent set already has the files (needs it anyway), they can be considered obsolete within the child set (it's OK, but you can free some space by reorganizing your sets).
    • Merge status CRITICAL (CRITICAL): One or more files to be merged are not found or otherwise bad in both the parent and the child set.

The ROMAlyzer's log will contain more useful details about each file it tried to read (or write):

ROMAlyzer log

Here's the log output for the analysis of a machine that contains a CHD:

14:49:52.584: analysis started
14:49:52.584: determining list of machines to analyze
14:49:52.584: done (determining list of machines to analyze)
14:49:52.584: 1 machine to analyze
14:49:52.584: analyzing 'voyager'
14:49:52.584: parsing XML data for 'voyager'
14:49:52.586: done (parsing XML data for 'voyager')
14:49:52.586: checking 3 files for 'voyager'
14:49:52.618: loading 'stv.u23' with CRC '0bed28b6' from '/home/games/mame/roms/voyager.zip' as 'stv.u23'
14:49:52.704: loading 'trident_tgui9680_bios.bin' with CRC '1eebde64' from '/home/games/mame/roms/voyager.zip' as 'trident_tgui9680_bios.bin'
14:49:52.710: loading '/home/games/mame/roms/voyager/voyager.chd'
14:49:52.711: CHD header information:
14:49:52.712:   tag: MComprHD
14:49:52.712:   version: 5
14:49:52.713:   compressors: lzma (LZMA), zlib (Deflate), huff (Huffman), flac (FLAC)
14:49:52.715:   number of bytes per hunk: 4,096
14:49:52.715:   number of bytes per unit: 512
14:49:52.716:   logical size: 19.41 GB (20,842,859,520 B)
14:49:52.718:   real size: 3.44 GB (3,698,419,901 B)
14:49:52.718:   SHA-1 check-sum: 8b94f2420f6abb40148e4ba6eed8819d8e85dbde
14:49:52.719:   raw SHA-1 check-sum: c6da45873ef656bdd973974ece02eba99412622a
14:49:52.720: using CHD v5 header check-sums for CHD verification
14:49:52.722: done (checking 3 files for 'voyager')
14:49:52.722: done (analyzing 'voyager')
14:49:52.723: 0 sets remaining
14:49:52.726: analysis ended - elapsed time = 00:00:00.142

Note:

  • UI updates to the report- and log-views are fairly expensive, so the ROMAlyzer runs remarkably faster when you don't watch these views while longer jobs are being processed!

ROMAlyzer settings

Nearly all of ROMAlyzer's options are combined on its Settings tab. They define how the ROMAlyzer runs and what steps it will perform.

ROMAlyzer settings

The settings in detail:

  • General analysis flags and limits
    • Flags
      • Append: When checked, the analysis report is appended to the existing report. Otherwise the report is cleared (recommended).
      • Scroll: Automatically scroll the report so that the last / currently processed entry is always visible?
      • Select: When this flag is set, selecting an entry in the ROMAlyzer report will cause the corresponding item in the machine list to be selected as well.
    • Expansion
      • File info: File (dump) information is automatically expanded when this option is set.
      • Check-sums: Calculated check-sums will be auto-expanded when this option is on.
    • Hashes
      • CRC-32: Calculates CRC-32 check-sums (and uses them for ROM verification).
      • SHA-1: Calculates SHA-1 hashes (and uses them for ROM verification).
      • MD5: Calculates MD5 hashes (and uses them for ROM verification, if available -- this should be kept disabled because MD5 is anyway no longer part of the XML data unless you're using a fairly old version of the emulator!).
    • Limits
      • File size: Files larger than this limit (in MB) will not be loaded / analyzed. For ZIP-/7z-archives this is the uncompressed size of member-files. A value of 0 means no limit (which is totally safe).
      • Log size: When the number of lines in the ROMAlyzer log exceeds this limit, the oldest line will be removed. A value of 0 means no limit (we recommend to limit the log to a few thousand lines).
      • Reports: When the number of items in the report view exceeds this limit, older items will be removed from it. A value of 0 means no limit (we recommend to limit the report to a few thousand items).
    • Backup settings
      • Create backups in this folder: When enabled and a valid (= writable) backup folder has been specified, backup copies will be created before files are modified / overwritten. The ROMAlyzer will automatically create sub-directories inside the backup folder as required to mimic the absolute paths of the original files.
  • Enable CHD manager: Enables/disables the use of the CHD manager which will operate whenever a set contains one or more CHDs.
    • Flags
      • Verify CHDs: When this option is set, chdman verify will be called for each CHD the ROMAlyzer stumbles upon.
      • Update CHDs: Enabling this switch causes the ROMAlyzer to call chdman copy whenever a CHD is older than the current CHD version (CHD v5).
    • Paths
      • CHD manager (chdman): Specify the path to the chdman executable file (mandatory).
      • Temporary working directory: This folder will be used to store temporary data when working on CHDs.
  • Enable set rewriter / collection rebuilder: Enables/disables the set rewriter and collection rebuilder features (the latter also requires the check-sum database!).
    • Flags
      • Rewrite while analyzing: When this option is set, the ROMAlyzer will automatically run the set rewriter for each set it has successfully analyzed. Otherwise the set rewriter can only be triggered manually through the report's context-menu.
      • Good dumps only: Sets will only be rewritten automatically when all their dumps are considered good (recommended). This setting is only relevant when Rewrite while analyzing is enabled. You can always trigger set rewriting manually from the context menu, though.
      • Self-contained: Self-contained sets will contain all ROMs that a set requires and will thus not need any parent sets to work. However, we recommend disabling this (as it takes a lot more disk space than is actually required), causing the set rewriter to produce space-efficient sets which will automatically be merged (by the emulator, upon loading) with the required ROMs from its parent(s) (the search is hierarchical, so ROMs could also be in the parent's parent - the depth of the hierarchy is theoretically unlimited, but as far as we can tell it's not more than 1 or 2 levels in real world).
      • Abort on error: When enabled (default), both the set-rewriter and the collection rebuilder will abort reproduction of a set when a file I/O error occurs upon reading from source data (or the dump cannot be found where it's expected according to the check-sum database), otherwise they will continue and try to rebuild all sub-sequent dumps. Note that the check-sum database could have records for one or more of the other required dumps that point to some files which are probably fine, or further dumps stored in the same source file (archive) could still be read successfully, so disabling abort on error can actually have a positive effect.
    • Reproduction
      • ZIPs (built-in): This selects the ZIP reproduction type using built-in ZIP compression through minizip (recommended).
        • Unique CRCs: In rare cases machines use multiple dumps that have the same CRC, and it may actually be sufficient to store the file only once - however, there are also cases where the same CRC is produced for different content (for example, see 'naomigd'). Therefore enabling this option is not recommended!
        • Compression: Sets the compression level (0 = no compression / fastest, 9 = maximum compression / slowest, default is 6).
        • Add ZIP comment: When enabled, the ROMAlyzer will add a small ZIP comment with the generating program's name / version and the reproduction date (i.e. Created by QMC2 v0.49 (2/19/15 12:45 PM)). Otherwise there'll be no such comment in the generated ZIP archives.
        • ROM sets will be reproduced as ZIP archives named as the respective machines.
      • ZIPs (libarchive): This selects the ZIP reproduction type using external ZIP compression through libarchive (this option is only available when support for libarchive was explicitly enabled during the build!).
        • Unique CRCs: In rare cases machines use multiple dumps that have the same CRC, and it may actually be sufficient to store the file only once - however, there are also cases where the same CRC is produced for different content (for example, see 'naomigd'). Therefore enabling this option is not recommended!
        • Compression: When set to On compression at (ZIP default) level 6 will be performed, otherwise (Off) files are just stored in the ZIP with no compression (equivalent to compression level 0 above).
        • ROM sets will be reproduced as ZIP archives named as the respective machines.
      • Sub-directories: This selects the sub-directory reproduction type.
        • ROM sets will be reproduced as regular files in sub-folders named as the respective machines.
    • Paths
      • Output directory: This folder is used to store all rewritten / exported sets (mandatory). Important: NEVER use one of your primary ROM paths here!!!
      • Addl. ROM path: If checked and an additional ROM path is given (= non-empty), this will be used as a prefixed ROM path. That is, ROM paths entered here will have precedence and could thus be used to present update ROMs to the ROMAlyzer which will automatically be merged with the ones in the primary ROM path(s).
    • Collection rebuilder specific flags
      • Use hash cache: When this options is enabled, the collection rebuilder will pre-load all available check-sums from the database in order to speed up hash look-ups during rebuild operations. This will use additional memory so it's optional (about 35 MB per 100K hashes).
      • Dry run mode: In dry run mode the collection rebuilder will not produce any output. This is good for quickly checking "what if" and for rapid generation of a fix.dat file.
      • CHD handling: Choose the mode in which CHDs are handled.
        • Don't reproduce: CHD files are completely ignored / will not be reproduced.
        • Create hard links: Hard links to the source CHDs are created in the output path instead of copying the data. This requires that the source and the target CHD paths are on the same file system; on Windows this will only work with NTFS. The collection rebuilder will spit related warnings (to its log) if the files do not belong to the same file system, automatically falling back to copy mode (see Copy files below). This setting is recommended!
        • Create symbolic links: Symbolic links to the source CHDs are created in the output path instead of copying the data.
        • Copy files: The source CHDs are copied to the target CHDs.
        • Move files: The source CHDs are moved / renamed to the target CHDs. If both the source and the target CHDs belong to the same file system, the source CHDs get quickly moved (renamed) to their target CHD names. Otherwise they are copied and their source files are removed.
  • Enable check-sum database: Enables/disables the use of the check-sum database which keeps pointers to files in your local file-system(s) and the SHA-1 / CRC-32 check-sums of the data they carry. When enabled, the check-sum database will be used by the ROMAlyzer as a repository for dumps not existing in the expected files/folders (i.e. inside one of your ROM paths). Note that since the scanned data is not expected to be structured in any way this makes for an easy-to-use vehicle for ROM updates (which is its main purpose). It's important that you keep the database up-to-date because the ROMAlyzer assumes that the data is current!
    • Scanned paths: Paths listed (and enabled) here will be scanned. Click the + button to add a path, and the - button to remove all selected paths. A running scan needs to be restarted for changes to take effect!
    • Incremental: When enabled, only files that were changed/ignored since/during the last scan will be scanned again and the database will be prepared accordingly - otherwise the database will be reinitialized (cleared). A running scan needs to be restarted for changes to take effect!
    • Deep: When enabled (the recommended default), all scanned members of ZIP or 7z archives will be uncompressed in order to recalculate their check-sums (SHA-1, CRC and dump size), otherwise the check-sum scanner will rely on the header check-sums (CRC and dump size only). A running scan needs to be restarted for changes to take effect! We recommend that you only disable deep scans when you're absolutely sure that all scanned paths contain only clean archives with no data integrity issues! You've been warned :).
      • IMPORTANT: The CRC and size combination is not unique, and there are even known CRC/size duplicates within MAME itself. 100% clean rebuilds can only be guaranteed for deep scans!
      • When QMC2 was built with support for libarchive and deep scans are enabled you will also have the option to scan the supported archive formats (ZIP and 7-zip) through libarchive instead of the built-in decompressors (minizip / zlib / LZMA lib). Since libarchive has no concept of a header check-sum non-deep scanning cannot be performed through it.
        • Regarding libarchive's support for 7-zip please note that when archives were created with header compression turned on QMC2 will not be able read them through this method. Make sure you turn it off upon archive creation - i. e. use 7za a -mhc=off archive.7z * to create an archive - or use the built-in support for 7-zip which reads those archives even with compressed headers.
    • Cache: When enabled (the default is disabled), scanned check-sums are cached (held in memory) during the scan which will improve the overall scanning speed enormously by much faster hash look-ups (at the cost of additional memory usage of about 35 MB per 100K scanned objects, released after use).
    • Database path: Path to the check-sum database file. A running scan needs to be restarted for changes to take effect!
    • Status: Displays the current status of the database & scanner.
    • Scanner control
      • Open / Close log: Opens / closes the scanner log window.
      • Start / Stop scanner: Starts / stops the scanner (which runs in a separate thread). While the scanner is running a Pause / Resume button will be shown right of the Start / Stop scanner button which can be used to pause / resume the scanner at (nearly) any time.

Check-sum finder

The check-sum finder allows for searching an SHA-1 or CRC check-sum in all available sets (again, the search is performed on the emulator's XML data). You can use it to find where a dump is used, to qualify the status of this dump in the respective sets and to figure out the file locations where the dumps are actually loaded from.

The context-menu of a ROM or CHD item in the report view has a corresponding short-cut for finding a certain dump easily:

ROMAlyzer check-sum search

When the check-sum database is enabled the availability of the entered SHA-1 or CRC check-sum will be indicated by displaying a colored database icon left of the Search button (green = good, red = bad, gray = unknown). It will also show a database icon in the Status column whenever it found the check-sum (only) in the database:

ROMAlyzer check-sum finder

Rewriting sets

You can enable the so called set rewriter in the ROMAlyzer settings in order to recreate clean new ZIPs or sets as regular files in machine-folders (reproduction in 7z format is not supported). The actual rewriting of sets can either be triggered manually through each checked set's context-menu in the report view, or automatically while analyzing.

ROMAlyzer rewrite set context-menu

Important things to note about the set rewriter:

  • Take backups of your primary ROM data before you replace it with the ZIPs created by the set rewriter!
  • NEVER use one of your primary ROM paths as the output directory for the set rewriter!!!
  • When the source data is bad and/or incomplete, the results will not be better. So, first get your ROM sets working before you even dare to run the set rewriter in order to clean them up!
  • As a general rule of thumb you should rewrite all clone sets whenever you rewrite a parent set (this is to avoid possible merge conflicts when parent/clone relationships have been reorganized by the MAME devs).
  • When you have update ROMs, you can point the set rewriter to them (see Additional ROM path in the ROMAlyzer settings) or use the check-sum database to make them available for rewriting.
    • The additional ROM path takes a semicolon-separated list of paths in the same way as MAME accepts it for the rompath option (the resulting ROM path will be prefixed with the additional path(s) you enter here, so they have precedence).
    • Although both approaches can be used in parallel, we recommend to disable the additional ROM path setting and to instead enable/use the newer check-sum database because it's much more powerful and flexible.

Now, when you hit the Rewrite set context-menu action, you'll find this in the log:

19:54:23.773: set rewriter: rewriting space-efficient set 'frogger' to '/home/games/mame/export/frogger.zip'
19:54:23.773: set rewriter: loading 'frogger.607' with CRC '05f7d883' from '/home/games/mame/roms/frogger.zip' as 'frogger.607'
19:54:23.775: set rewriter: loading 'frogger.610' with CRC '31d7eb27' from '/home/games/mame/roms/frogger.zip' as 'frogger.610'
19:54:23.777: set rewriter: loading 'pr-91.6l' with CRC '413703bf' from '/home/games/mame/roms/frogger.zip' as 'pr-91.6l'
19:54:23.779: set rewriter: loading 'frogger.26' with CRC '597696d6' from '/home/games/mame/roms/frogger.zip' as 'frogger.26'
19:54:23.780: set rewriter: loading 'frogger.609' with CRC '7380a48f' from '/home/games/mame/roms/frogger.zip' as 'frogger.609'
19:54:23.782: set rewriter: loading 'frsm3.7' with CRC 'aca22ae0' from '/home/games/mame/roms/frogger.zip' as 'frsm3.7'
19:54:23.784: set rewriter: loading 'frogger.27' with CRC 'b6e6fcc3' from '/home/games/mame/roms/frogger.zip' as 'frogger.27'
19:54:23.785: set rewriter: loading 'frogger.608' with CRC 'e8ab0256' from '/home/games/mame/roms/frogger.zip' as 'frogger.608'
19:54:23.787: set rewriter: loading 'frogger.606' with CRC 'f524ee30' from '/home/games/mame/roms/frogger.zip' as 'frogger.606'
19:54:23.788: set rewriter: writing new space-efficient set 'frogger' in '/home/games/mame/export/frogger.zip'
19:54:23.789: set rewriter: deflating 'frogger.26' (uncompressed size: 4.00 KB)
19:54:23.791: set rewriter: deflating 'frogger.27' (uncompressed size: 4.00 KB)
19:54:23.792: set rewriter: deflating 'frogger.606' (uncompressed size: 2.00 KB)
19:54:23.794: set rewriter: deflating 'frogger.607' (uncompressed size: 2.00 KB)
19:54:23.796: set rewriter: deflating 'frogger.608' (uncompressed size: 2.00 KB)
19:54:23.797: set rewriter: deflating 'frogger.609' (uncompressed size: 2.00 KB)
19:54:23.799: set rewriter: deflating 'frogger.610' (uncompressed size: 2.00 KB)
19:54:23.800: set rewriter: deflating 'frsm3.7' (uncompressed size: 4.00 KB)
19:54:23.802: set rewriter: deflating 'pr-91.6l' (uncompressed size: 0.03 KB)
19:54:23.804: set rewriter: new space-efficient set 'frogger' in '/home/games/mame/export/frogger.zip' successfully created
19:54:23.804: set rewriter: done (rewriting space-efficient set 'frogger' to '/home/games/mame/export/frogger.zip')

Comparing this with rewriting a clone set (froggers) which merges some ROMs from its parent (frogger) you'll notice that redundant files will be removed automatically. That's what space-efficient reproduction means:

19:55:33.641: set rewriter: rewriting space-efficient set 'froggers' to '/home/games/mame/export/froggers.zip'
19:55:33.642: set rewriter: loading 'vid_h2.bin' with CRC '04c027a5' from '/home/games/mame/roms/froggers.zip' as 'vid_h2.bin'
19:55:33.643: set rewriter: loading 'frogger.607' with CRC '05f7d883' from '/home/games/mame/roms/frogger.zip' as 'frogger.607'
19:55:33.644: set rewriter: loading 'frogger.610' with CRC '31d7eb27' from '/home/games/mame/roms/frogger.zip' as 'frogger.610'
19:55:33.645: set rewriter: loading 'pr-91.6l' with CRC '413703bf' from '/home/games/mame/roms/frogger.zip' as 'pr-91.6l'
19:55:33.647: set rewriter: loading 'vid_f2.bin' with CRC '637a2ff8' from '/home/games/mame/roms/froggers.zip' as 'vid_f2.bin'
19:55:33.649: set rewriter: loading 'epr-1036.1k' with CRC '658745f8' from '/home/games/mame/roms/froggers.zip' as 'epr-1036.1k'
19:55:33.650: set rewriter: loading 'frogger.609' with CRC '7380a48f' from '/home/games/mame/roms/frogger.zip' as 'frogger.609'
19:55:33.652: set rewriter: loading 'vid_l2.bin' with CRC '8a4389e1' from '/home/games/mame/roms/froggers.zip' as 'vid_l2.bin'
19:55:33.653: set rewriter: loading 'vid_d2.bin' with CRC 'c103066e' from '/home/games/mame/roms/froggers.zip' as 'vid_d2.bin'
19:55:33.655: set rewriter: loading 'frogger.608' with CRC 'e8ab0256' from '/home/games/mame/roms/frogger.zip' as 'frogger.608'
19:55:33.659: set rewriter: loading 'vid_e2.bin' with CRC 'f08bc094' from '/home/games/mame/roms/froggers.zip' as 'vid_e2.bin'
19:55:33.661: set rewriter: loading 'vid_j2.bin' with CRC 'fbdfbe74' from '/home/games/mame/roms/froggers.zip' as 'vid_j2.bin'
19:55:33.663: set rewriter: removing redundant file 'frogger.608' with CRC 'e8ab0256' from output data
19:55:33.663: set rewriter: removing redundant file 'frogger.609' with CRC '7380a48f' from output data
19:55:33.663: set rewriter: removing redundant file 'frogger.610' with CRC '31d7eb27' from output data
19:55:33.663: set rewriter: removing redundant file 'frogger.607' with CRC '05f7d883' from output data
19:55:33.664: set rewriter: removing redundant file 'pr-91.6l' with CRC '413703bf' from output data
19:55:33.664: set rewriter: writing new space-efficient set 'froggers' in '/home/games/mame/export/froggers.zip'
19:55:33.665: set rewriter: deflating 'epr-1036.1k' (uncompressed size: 2.00 KB)
19:55:33.667: set rewriter: deflating 'vid_d2.bin' (uncompressed size: 2.00 KB)
19:55:33.669: set rewriter: deflating 'vid_e2.bin' (uncompressed size: 2.00 KB)
19:55:33.670: set rewriter: deflating 'vid_f2.bin' (uncompressed size: 2.00 KB)
19:55:33.671: set rewriter: deflating 'vid_h2.bin' (uncompressed size: 2.00 KB)
19:55:33.672: set rewriter: deflating 'vid_j2.bin' (uncompressed size: 2.00 KB)
19:55:33.674: set rewriter: deflating 'vid_l2.bin' (uncompressed size: 2.00 KB)
19:55:33.675: set rewriter: new space-efficient set 'froggers' in '/home/games/mame/export/froggers.zip' successfully created
19:55:33.675: set rewriter: done (rewriting space-efficient set 'froggers' to '/home/games/mame/export/froggers.zip')

This is contrary to self-contained reproduction which would keep those files and store them in the resulting ZIP:

08:16:54.874: set rewriter: rewriting self-contained set 'froggers' to '/home/games/mame/export/froggers.zip'
08:16:54.875: set rewriter: loading 'vid_h2.bin' with CRC '04c027a5' from '/home/games/mame/roms/froggers.zip' as 'vid_h2.bin'
08:16:54.878: set rewriter: loading 'frogger.607' with CRC '05f7d883' from '/home/games/mame/roms/frogger.zip' as 'frogger.607'
08:16:54.879: set rewriter: loading 'frogger.610' with CRC '31d7eb27' from '/home/games/mame/roms/frogger.zip' as 'frogger.610'
08:16:54.880: set rewriter: loading 'pr-91.6l' with CRC '413703bf' from '/home/games/mame/roms/frogger.zip' as 'pr-91.6l'
08:16:54.882: set rewriter: loading 'vid_f2.bin' with CRC '637a2ff8' from '/home/games/mame/roms/froggers.zip' as 'vid_f2.bin'
08:16:54.883: set rewriter: loading 'epr-1036.1k' with CRC '658745f8' from '/home/games/mame/roms/froggers.zip' as 'epr-1036.1k'
08:16:54.885: set rewriter: loading 'frogger.609' with CRC '7380a48f' from '/home/games/mame/roms/frogger.zip' as 'frogger.609'
08:16:54.887: set rewriter: loading 'vid_l2.bin' with CRC '8a4389e1' from '/home/games/mame/roms/froggers.zip' as 'vid_l2.bin'
08:16:54.888: set rewriter: loading 'vid_d2.bin' with CRC 'c103066e' from '/home/games/mame/roms/froggers.zip' as 'vid_d2.bin'
08:16:54.890: set rewriter: loading 'frogger.608' with CRC 'e8ab0256' from '/home/games/mame/roms/frogger.zip' as 'frogger.608'
08:16:54.891: set rewriter: loading 'vid_e2.bin' with CRC 'f08bc094' from '/home/games/mame/roms/froggers.zip' as 'vid_e2.bin'
08:16:54.893: set rewriter: loading 'vid_j2.bin' with CRC 'fbdfbe74' from '/home/games/mame/roms/froggers.zip' as 'vid_j2.bin'
08:16:54.895: set rewriter: writing new self-contained set 'froggers' in '/home/games/mame/export/froggers.zip'
08:16:54.897: set rewriter: deflating 'epr-1036.1k' (uncompressed size: 2.00 KB)
08:16:54.901: set rewriter: deflating 'frogger.607' (uncompressed size: 2.00 KB)
08:16:54.905: set rewriter: deflating 'frogger.608' (uncompressed size: 2.00 KB)
08:16:54.907: set rewriter: deflating 'frogger.609' (uncompressed size: 2.00 KB)
08:16:54.909: set rewriter: deflating 'frogger.610' (uncompressed size: 2.00 KB)
08:16:54.911: set rewriter: deflating 'pr-91.6l' (uncompressed size: 0.03 KB)
08:16:54.913: set rewriter: deflating 'vid_d2.bin' (uncompressed size: 2.00 KB)
08:16:54.915: set rewriter: deflating 'vid_e2.bin' (uncompressed size: 2.00 KB)
08:16:54.917: set rewriter: deflating 'vid_f2.bin' (uncompressed size: 2.00 KB)
08:16:54.919: set rewriter: deflating 'vid_h2.bin' (uncompressed size: 2.00 KB)
08:16:54.920: set rewriter: deflating 'vid_j2.bin' (uncompressed size: 2.00 KB)
08:16:54.922: set rewriter: deflating 'vid_l2.bin' (uncompressed size: 2.00 KB)
08:16:54.924: set rewriter: new self-contained set 'froggers' in '/home/games/mame/export/froggers.zip' successfully created
08:16:54.924: set rewriter: done (rewriting self-contained set 'froggers' to '/home/games/mame/export/froggers.zip')

You can also rewrite sets that are actually not available in your ROM path in case the check-sum database is enabled and pointers to all corresponding dumps are available in the database. The ROMAlyzer will indicate this by adding database icons for dumps it could find (only) in the database:

ROMAlyzer report for items referred to by the check-sum database

Don't get this screen shot wrong: although it looks as if the sets are in a good shape they are not available in the ROM path!

The ROMAlyzer log will indicate this by showing messages similar to this one instead of the typical loading messages when analyzing a set:

15:16:00.476: check-sum database: using member '<source_file>' from archive '<source_archive>' with SHA-1 '<sha1>' and CRC '<crc>' as '<target_file>'

In order to make them available to the emulator we'd have to rewrite the sets and copy the results to one of our ROM paths.

Notes:

  • If you plan to rewrite your complete ROM collection (i.e. to clean it up from obsolete stuff), move all ROM files away from your primary ROM path(s) to one or more backup folders, then scan these backup folders with the check-sum scanner and let the analyzer rewrite all sets afterwards. Doing so not only ensures that you have a backup but also causes the rewritten sets to be reshuffled from pointers in the database and to not be checked again in the analysis step, which the check-sum scanner already did for us. It's usually faster this way (especially when you do this several times with different reproduction settings), however, it depends on a number of local parameters like the OS, the file-system in use or the overall (I/O) performance, and scanning alone also takes its time. But there's another important advantage of this approach: renamed sets will automatically be fixed.
  • However, the set-rewriter wasn't really designed / optimized for this kind of job and may be too slow for you. You should use the new ROM collection rebuilder sub-feature instead which was specifically designed for this purpose (and more)!

ROMAlyzer tools

In system-mode you'll find this tool-button left of the Analyze button with an attached menu containing related tools:

ROMAlyzer tools menu

Tool-menu item descriptions:

  • Import from data file: This will import the names of all sets contained in a specified data file which is assumed to be in clrmamepro compatible fix.dat format! Importing in this context means that the set names will be used as the ROMAlyzer's match patterns. Any set names in the fix.dat that are unknown / not valid for the emulator in use will be dropped silently.
  • Export to data file: If one or more analyzed sets contain any bad or missing dumps, this item will be enabled and could be used to create a clrmamepro compatbile fix.dat data file. Note that this will only cover those sets which are currently part of the report view!

Check-sum database

The check-sum database is used to store & retrieve pointers to files in your local file-system(s) and the SHA-1 / CRC-32 check-sums of the data they carry. When this feature is enabled in the ROMAlyzer settings, the check-sum database will be used by the check-sum finder and the set rewriter as a fall back repository for dumps that don't exist inside one of your ROM paths (but do exist elsewhere perhaps, i.e. in a ROM update folder or a backup folder).

The ROM collection rebuilder even uses this database as the only source of information. It's thus only available when the check-sum database is enabled.

Scanned data is not expected to be structured in any way, so this allows for easy ROM updates which is what this feature has been mainly implemented for :).

Included folders (and their sub-folders) will be scanned for all files they contain, and each file will be scanned individually depending on what type of file it is:

  • ZIP scan: reads all data in all members contained in ZIP archives and calculates their check-sums (SHA-1, CRC-32 and size) if deep scan is enabled, otherwise relies on the ZIP header check-sums (CRC-32 and size)
  • 7Z scan: reads all data in all members contained in 7-zip archives and calculates their check-sums (SHA-1, CRC-32 and size) if deep scan is enabled, otherwise relies on the 7-zip header check-sums (CRC-32 and size)
  • CHD scan: reads CHD header information and relies on the check-sums it contains (SHA-1 and size)
  • File scan: reads all data in regular files (= not a ZIP, 7-zip or CHD) and calculates the check-sums (SHA-1, CRC-32 and size)

It's important that you keep the database up-to-date because the ROMAlyzer assumes that its data is current!

So keep an eye on the age of stored data and rescan the involved folders whenever you update any files in them.

Also, please note that nested ZIP or 7Z archives (i.e. a ZIP in a ZIP in a ZIP...) aren't really supported by the scanner. They are seen as regular archive members, so their check-sums wouldn't be very useful for us.

You can start / stop (or pause / resume) the scanner from the Scanner control on the ROMAlyzer settings page:

ROMAlyzer check-sum scanner control (scanning) ROMAlyzer check-sum scanner control (idle)

The scanner runs in a separate thread to not interfere with the GUI. It has its own log which you can open / close on demand:

ROMAlyzer check-sum scanner log

Incremental scans

When the scanner's Incremental switch is enabled, only files that were changed since the last scan - or ignored during the last scan because the checks-sums they carried were duplicates in the database - will be scanned again. The decision is made by comparing the time stamp of the last scan with each file's modification time.

Also, obsolete entries (= files that are no longer contained in the scanned paths) and outdated ones (= files that have changed since the last scan) will automatically be removed from the database during the preparation steps that are performed in this mode before the actual scanning starts. This requires reading all rows in the database once (in preparation step 1) to find all the stored paths, of course, and may take some time depending on the size of the database.

Note that in case of ZIP- or 7z-archives, the modification time of the archive file (NOT the modification times of the contained files!) is used to find out if something changed. So in case an archive is updated without changing the modification time, the check-sum scanner will assume that the file wasn't changed and thus remove it from the list of (re-)scanned files. To avoid this, make sure that you

  • have set up system date and time correctly to avoid general clock skew issues
  • use tools that cleanly update the archive's modification time when changing its contents (tools that don't do this should be fixed ASAP!)
  • touch the files in question as last resort like so: find /folder/where/rom/updates/are/stored -exec touch {} \; (this example would force a rescan of the complete folder and its sub-folders by running touch on every contained file)

We generally recommend that you keep incremental scanning enabled at all time (it is enabled by default), except if you explicitly want/need to recreate the database from scratch for whatever reason. One possible reason could be that you know that nearly every file in the scanned paths was changed (i.e. after ROM sets were rebuilt), in which case it's much faster to switch off incremental scanning temporarily, start the scanner (which will simply recreate the database from scratch to prepare a full scan) and switch incremental scanning on again, than to let the scanner remove all entries via expensive database transactions.

ROM collection rebuilder

The ROM collection rebuilder is a ROMAlyzer sub-feature which was specifically designed to - as the name suggests - rebuild complete ROM collections from scratch in the background. The rebuilding process runs in a separate thread so that the (potentially heavy) CPU and I/O load it might generate has no impact on the GUI.

This feature is fully dependent on the check-sum database and uses the pointers the database has to offer for available dumps in order to reshuffle newly created sets. So it will only work as expected when the check-sum database has been filled with the required data by scanning your ROM / backup / update folder(s)!

Despite this difference to the set-rewriter it basically has similar functionality and shares most settings with it - only the additional ROM path setting and the good dumps only switch are ignored by the ROM collection rebuilder, because it only uses the check-sum database for finding dumps and it will reproduce what's available, regardless of missing dumps. Also, rewrite while analyzing is obviously not applicable to the ROM collection rebuilder since it doesn't analyze anything. All other settings have the same meaning in both the set-rewriter and the ROM collection rebuilder.

Rebuilding can be performed according to the XML from the current default emulator (the one you're using in QMC2) or any foreign XML read from an external file. In particular, you can use the DATs / XMLs from progetto-SNAPS to rebuild a ROM collection valid for the respective emulator version (provided the required dumps exist in your ROM vault and you've scanned the relevant folder(s), of course). You can also use a clrmamepro compatible fix.dat data file as input for the rebuilder, of course.

When running in software-mode (called software collection rebuilder in this case) you can also use software-list hash XML files here, so rebuilding is automatically limited to the chosen software-list.

This approach should also work fine with XML from any foreign emulator as long as its XML format is MAME-compatible! However, this hasn't been tested yet. So if you do, please let us know your results!

Besides system- and software-modes, the collection rebuilder can be used in two different operation modes:

  • Rebuild mode: This is the normal mode in which the collection rebuilder will actually produce new sets on disk.
  • Dry run mode: In dry run mode the collection rebuilder will not produce any output. It can be used to quickly check "what if" (before running a time consuming rebuild operation) or to rapidly create a fix.dat file.

Note that whatever the current mode may be, when the collection rebuilder gets called through a UI integration feature (i.e. context menu actions) it will run the job in the currently set operation mode.

The following screen shot shows the collection rebuilder in action while rebuilding ROM sets for the current default emulator:

ROM collection rebuilder

To use an external XML file as input for the ROM collection rebuilder, use the drop-down menu at the top of the dialog and choose "Select XML file...". Every file you select will be added to the drop-down list so you can easily reuse it later:

XML source selection

Whenever an external XML source is chosen in the drop-down menu, additional entry fields will be shown to allow for overwriting the XML entity names that define sets, ROMs and disks. You'll also find a removal tool-button right of the drop-down menu in this case. Clicking it will delete the current XML source from the list:

Specifying XML entity names

Clicking Start rebuilding / Start dry run will start the rebuild / dry run operation and its activity will be written to the log. All generated files will be written to the set-rewriter's output directory (see ROMAlyzer settings), potentially overwriting files that might reside in this folder!

You can pause / resume running rebuilds / dry runs as well as stop them at (nearly) any time. Pausing and stopping are asynchronous operations, meaning that the collection rebuilder will first finish the set that it's currently rebuilding in order to have a clean checkpoint for a later restart.

The meaning of the checkpoint indication in the drop-down list is as follows:

  • Checkpoint available: A checkpoint has been stored for this XML source because a previous rebuild / dry run (with this XML source as input) was prematurely interrupted. You can restart from this checkpoint, and you will therefore be asked if you want to do so as soon as you click Start rebuilding or Start dry run!
  • No checkpoint available: There is no checkpoint for this XML source, either because a rebuild / dry run (with this XML source as input) hasn't been run before or the previous rebuild / dry run was completed.

You can optionally enable the use of a filter expression (Qt regular expression, see QRegExp for details) in order to include or exclude sets whose IDs match the given pattern. The pattern syntaxes you can choose from correspond to the QRegExp::PatternSyntax enum. The exact match toggle button (Exact match icon) decides if the filter expression has to match exactly (enabled), or if we're searching for matching sub-strings (disabled).

When the XML source is the current default emulator you will also be able to filter the exported sets by their ROM states when enabling filter states. If enabled, a set will be included in the rebuild process only when its state is among the checked ones.

The Missing dumps viewer icon-button in the lower right corner will open the missing dumps viewer which contains a list of missing ROMs and disks for the currently active or last rebuild / dry run operation:

Missing dumps viewer

Clicking Export to data file will open a browser to select a file name used to export the missing dumps as a clrmamepro compatible fix.dat data file. When Selected dumps only is enabled, only those dumps that are selected in the list will be exported, otherwise all missing dumps will be included in the export.

Additional notes:

  • When rebuilding sets in reproduction mode directories you should enable self-contained because a number of MAME drivers appear to have issues with merging dumps from parents when they aren't stored in ZIP (or 7Z) archives.
  • For ZIP reproduction we recommend disabling self-contained which will result in space-efficient sets.

Video tutorial

There's also a 15 minute video tutorial on using the check-sum scanner and the collection rebuilder - see here!

Cache files / folders

QMC2 uses a number of so called cache files / folders to speed up loading whenever possible. So instead of asking the emulator over and over again (or loading data from the internet), relevant data is stored on disk and reused when available and up-to-date. The following table lists all of these caches:

Cache name

Default path

Description

ROM state cache <config_path>/mame.rsc The ROM state cache is used to quickly restore the individual ROM states of all sets when loading the machine-list views.
XML cache database <config_path>/mame-xml-cache.db The XML cache database replaces the former XML data cache file and is used to store & retrieve per-machine XML data on demand very quickly. Unnecessary white-space is stripped from the XML data before it's stored in the database.
Machine list cache <config_path>/mame.mlc The machine list cache (aka MLC) represents the relevant excerpt (parsed from the XML data) which is displayed in the columns of all machine list views. Its format is purely internal and may change at any time.
<config_path>/mame.mlc.filtered This is the filtered version of the machine list cache, exclusively used by QMC2 Arcade (optional). You have to create and update it manually through the Machine list filter page on the Arcade mode setup dialog.
Machine list database <config_path>/mame-machine-list.db The machine list database (aka MLDB) is the SQLite3 database version of the machine list cache, used by custom machine list views.
Software-list XML cache database <config_path>/mame-swl-cache.db The software-list XML cache database replaces the former software-list cache file and is used to store & retrieve software XML data on demand very quickly. Unnecessary white-space is stripped from the software-list XML data before it's stored in the database.
Icon cache database <config_path>/mame-icon-cache.db The icon cache database stores decompressed icon data (SQLite3 blobs in ICO format) already mapped to machine IDs in order to speed up loading them.
Software-state cache <config_path>/sw-state-cache/ Software-states, indicated as icons in software-lists, are cached in the software-state cache folder containing cache files for all software-lists that have already been checked (<software_list>.ssc).
Slot-info cache <config_path>/mame.sic Slot-information from -listslots is stored in the slot-info cache file in order to speed up initial loading of the device mapper.
YouTube cache <config_path>/youtube/ The YouTube cache folder is used to store preview-images (<video_id>.png) and meta-data for attached videos that were loaded from YouTube and displayed in / used by the video player. The folder also contains the YouTube index file (<variant>.yti) which contains the meta-data and image assignments.

Besides these caches there are also databases for other stuff:

Database name

Default path

Description

User data database <config_path>/mame-user-data.db This SQLite 3 database is used to store & retrieve rank information and personal comments per machine. This database also stores hidden software-lists, software favorites and pointers to scanned system- and software-manuals per system in separate tables.
Check-sum database (systems) <config_path>/<variant>-checksum.db This SQLite 3 database is used by the ROMAlyzer in system-mode to store & retrieve paths to dumps available in your file-system by SHA-1 and/or CRC.
Check-sum database (software) <config_path>/<variant>-software-checksum.db This SQLite 3 database is used by the ROMAlyzer in software-mode to store & retrieve paths to dumps available in your file-system by SHA-1 and/or CRC.
DAT-info database <config_path>/mame-dat-info.db This SQLite 3 database is used to provide a combined data store for all supported dat-info sources (emu-info, machine-info and software-info). The DAT-info sources are re-imported (into the database) automatically during reload whenever a DAT-info source file's modification date changes or a different source file is used (you can also manually reimport each source individually in the configuration). Otherwise the data is directly fetched from the database. QMC2 Arcade supports this database as well and also updates it when required.

Regarding the actual value of <config_path> please refer to this section. The value of <variant> is either qmc2-sdlmame (Linux / UNIX / Mac OS X) or qmc2-mame (Windows).

Key sequences / short cuts

Several functions (or actions in Qt jargon) can be accessed via key sequence short cuts. The following table lists all of them together with their default key-sequence mappings:

Key sequence (default)

Description

Ctrl+P Play the currently selected machine (start emulation)
Ctrl+Shift+P Linux/Unix and Windows only: Play the currently selected machine (start emulation) in embedded mode
Ctrl+R Reload the entire machine list
Ctrl+J Copy the currently selected machine to the list of favorites
Ctrl+X Linux/Unix and Windows only: Stop any active processing, otherwise exit QMC2
Ctrl+O Linux/Unix and Windows only: Open the options/preferences dialog
Ctrl+I Housekeeping: Clear the image cache
Ctrl+M Housekeeping: Clear the ProjectMESS cache (in-memory and/or on-disk)
Ctrl+N Housekeeping: Clear the icon cache
Ctrl+T Housekeeping: Recreate the template configuration map (required if the XML options template are changed at run-time)
Ctrl+, Mac OS X only: Open the options/preferences dialog
Ctrl+Shift+C Housekeeping: Check the loaded template configuration map against the currently selected emulator's configuration options and their defaults
Ctrl+H QMC2 documentation browser
Ctrl+B About QMC2: Version, license, system info etc.
Ctrl+Q Linux/Unix and Windows: About Qt (version, license etc.)
Mac OS X: Stop any active processing, otherwise exit QMC2
Ctrl+S Check the current machine's ROM state individually and update its state in the ROM state cache
Ctrl+D Analyse (deep-scan) the current machine's ROM with the ROMAlyzer
Ctrl+Z Open the ROMAlyzer (system mode) to deeply analyze the ROMs of one or more system-sets
Ctrl+W Open the ROMAlyzer (software mode) to deeply analyze the ROMs of one or more software-sets
Ctrl+E Export the current ROM status to file
Ctrl+1 Check the ROM states of all machines and recreate the ROM state cache from scratch
Ctrl+2 Check the sample sets for machines that need samples
Ctrl+3 Check image and icon files for existence / accessibility / usability / obsoleteness
Ctrl+Alt+C Toggle ROM state filtering for status Correct
Ctrl+Alt+M Toggle ROM state filtering for status Mostly correct
Ctrl+Alt+I Toggle ROM state filtering for status Incorrect
Ctrl+Alt+N Toggle ROM state filtering for status Not found
Ctrl+Alt+U Toggle ROM state filtering for status Unknown
Ctrl+Shift+A Setup QMC2 Arcade
Alt+PgUp Increase the current machine's rank
Alt+PgDown Decrease the current machine's rank
F2 Rebuild the current machine's ROM set with the ROMAlyzer
F5 View machine list with full detail
F6 View parent/clone hierarchy
F7 View machines by category (only available when the use of catver.ini and/or category.ini has been enabled)
F8 View machines by version they were added to the emulator (only available when the use of catver.ini has been enabled)
F9 Reserved: Filtered machine list view (future)
F10 Check software-states (only available when the software-list detail is active)
F11 Toggle between full screen and windowed mode
F12 Launch QMC2 Arcade
Ctrl+Shift+F2 Rebuild the ROM sets of all tagged machines with the ROMAlyzer
Ctrl+Shift+T Tag the current machine
Ctrl+Shift+U Untag the current machine
Ctrl+Shift+G Toggle the tag mark of the current machine
Ctrl+Shift+L Tag all machines
Ctrl+Shift+N Untag all machines
Ctrl+Shift+I Invert all tags
Ctrl+Shift+S Check the ROM states of all tagged machines
Ctrl+Shift+D Analyze (run the ROMAlyzer on) all tagged machines
Ctrl+Shift+J Add all tagged machines to the favorites list
Ctrl+Shift+X Tag all visible machines (according to the current ROM state filter)
Ctrl+Shift+Y Untag all visible machines (according to the current ROM state filter)
Ctrl+Shift+Z Invert all tags of visible machines (according to the current ROM state filter)
Shift+Down Toggle tag mark of the current machine and move the cursor one item down
Shift+Up Toggle tag mark of the current machine and move the cursor one item up
Shift+F5 Software-list view-mode flat (only available when the software-list detail is active)
Shift+F6 Software-list view-mode tree (only available when the software-list detail is active)
Shift+F9 Run the external ROM tool on the currently selected machine
Ctrl+Shift+F9 Run the external ROM tool on all tagged machines

When Phonon features are enabled, the following short cuts will also be available:

Key sequence (default)

Description

Ctrl+Alt+P Audio player: Play / resume the current track
Ctrl+Alt+# Audio player: Pause the current track
Ctrl+Alt+S Audio player: Stop playback
Ctrl+Alt+Left Audio player: Jump to the start of the previous track
Ctrl+Alt+Right Audio player: Jump to the start of the next track
Ctrl+Alt+F Audio player: Fast forward within the current track (jump to the next track if the end is reached)
Ctrl+Alt+B Audio player: Fast backward within the current track (jump to the previous track if the start is reached)
Ctrl+Alt+PgUp Audio player: Raise volume
Ctrl+Alt+PgDown Audio player: Lower volume
Ctrl+Y Clear the YouTube (on-disk) image cache

Key sequences marked as reserved aren't available yet but planned to be used in the future.

Building and installing QMC2 from source

Preparations and notes

Get and extract the QMC2 source code from the download page to a local directory.

Note that the following sections assume you're using the newest code from SVN. Our recommendations with regard to this are:

  • On Linux / UNIX and Mac OS X you should be using the de-facto standard svn command (in case you haven't installed it yet, the package is most likely named subversion).

We also assume that all other requirements are met (i. e. that the right Qt, Xlib, SDL, ..., whatever libraries / headers are installed). This FAQ lists a few examples of what packages have to be installed on which platform or distribution.

Linux / UNIX

1. Install the required packages (including their dependencies)

It's a hard job to collect the names of required packages on all of the potential Linux / UNIX distributions out there, so we will not even try to do that (but we're still interested to hear from you if you have anything to share, of course!). Examples for some popular Linux distributions (Debian, Ubuntu, openSUSE, Fedora and Arch Linux) are included in this FAQ section, though.

What we basically need is this:

  • GNU make (gmake)
  • Any C/C++ compiler that Qt supports on the target OS / platform (typically gcc / g++)
  • Qt 4.8+ / Qt 5.1+ development packages or (better yet) a self-compiled Qt 4.8+ / Qt 5.1+ installation
    • Qt 5.0.x is not officially supported, however, it may work as well
    • Qt 4.8.7 is recommended
  • Any SVN client (subversion recommended)
  • X11 development packages
  • SDL 1.2.x or SDL 2.x.x development packages (2.x.x recommended)

2. Check out the source code from SVN

$ mkdir ~/src; cd ~/src
$ svn co https://svn.code.sf.net/p/qmc2/code/trunk qmc2
$ cd qmc2

or update the source code to the latest SVN revision

$ cd ~/src/qmc2
$ svn update

(or unpack a tar-ball)

3. Build and install QMC2 with distribution-specific configuration turned on

$ make DISTCFG=1
$ su
Password:
# make install DISTCFG=1
# logout

If no distribution-specific configuration is available, you'll see a warning that some .cfg file is missing and it will try a fall back to the default configuration for the given OS & platform... if that fails, try DISTCFG=0 (which is the default so you can also just omit it). If this fails as well, please contact us for support! It will probably help us if you'd include the output from make os-detect in this case:

$ make os-detect
Operating System ............ Linux
Distribution / OS version ... openSUSE_Tumbleweed
System information .......... Linux marvin 4.9.3-1-default #1 SMP PREEMPT Thu Jan 12 11:32:53 UTC 2017 (2c7dfab) x86_64 x86_64 x86_64 GNU/Linux
System cfg-file (ok) ........ arch/Linux.cfg
Distribution cfg-file (ok) .. arch/Linux/openSUSE_Tumbleweed.cfg

4. Clean up the source tree

$ make distclean DISTCFG=1

5. Optionally build & install QMC2 Arcade:

$ make arcade DISTCFG=1
$ su
Password:
# make arcade-install DISTCFG=1
# logout
$ make distclean DISTCFG=1

6. Optionally build & install Qt CHDMAN GUI:

$ make qchdman DISTCFG=1
$ su
Password:
# make qchdman-install DISTCFG=1
# logout
$ make distclean DISTCFG=1

7. Optionally convert & install the man-pages:

$ make man
$ sudo make man-install

Mac OS X

Please follow the steps in this FAQ to build and install QMC2 from source on Mac OS X 10.6 (Snow Leopard), 10.7 (Lion), 10.8 (Mountain Lion), 10.9 (Mavericks), 10.10 (Yosemite), 10.11 (El Capitan) or 10.12 (macOS Sierra)!

Windows

Building QMC2 with MinGW (GCC)

  • Prerequisites:
    • Get, install and setup the new MSYS2 based MAME dev-tools for your platform (32- and/or 64-bit). Keep it up to date!
    • Open conemu.bat from the MSYS2 installation folder.
    • Install the SDL 2 and Qt 4 development packages: pacman -S mingw-w64-x86_64-SDL2 mingw-w64-x86_64-qt4
    • Change the current working directory to the folder where you extracted the QMC2 source code or where you keep your local SVN working copy.
  • Main GUI:
    • Run make or make -j<#CPUs + 1> to build the main GUI's binary.
    • After compilation is complete, you'll find the resulting binary (qmc2-mame.exe) in the release/ folder.
    • Execute release/qmc2-mame.exe to run the main GUI.
  • QMC2 Arcade (optional):
    • Run make arcade or make -j<#CPUs + 1> arcade to build the QMC2 Arcade binary.
    • After compilation is complete, you'll find the resulting binary (qmc2-arcade.exe) in the arcade/release/ folder.
    • Execute arcade/release/qmc2-arcade.exe to run QMC2 Arcade.
  • Qt CHDMAN GUI (optional):
    • Run make qchdman or make -j<#CPUs + 1> to build the Qt CHDMAN GUI binary.
    • After compilation is complete, you'll find the resulting binary (qchdman.exe) in the tools/qchdman/release/ folder.
    • Execute tools/qchdman/release/qchdman.exe to run Qt CHDMAN GUI.
  • Cleaning up the source tree:
    • make distclean

Building QMC2 with Visual C++ 2010

  • For correct embedding of static images that QMC2 uses (mostly icons) it's necessary to manually copy all image files from data\img\classic\ to data\img\, overwriting the existing symbolic links.
  • If you'd like to exchange some images with those in other image sets (see sub-directories below data\img\, i. e. crazy\ or cubes\), just copy these files over the ones that are in data\img\ now.
  • Edit the batch script scripts\generate-vcprojects.bat and adjust the path variables at the beginning of the script. Note that the script requires sed for Windows (and optionally TortoiseSVN when using code from the SVN repository).
  • When you're building for 64-bit, remove any existing project and solution files related to it, otherwise you'll get broken projects in Visual Studio later: del *-x64.* && del arcade\*-x64.* && del tools\qchdman\*-x64.*.
  • Open a command prompt window (cmd.exe) and change the current working directory to the path where you extracted the QMC2 source code (or where you keep your local SVN working copy) and run scripts\generate-vcprojects.bat. This will create additional sub-directories (debug\ and release\) for each project and generate 6 VC++ project files: qmc2-mame[-x64].vcxproj, arcade\qmc2-arcade[-x64].vcxproj and tools\qchdman\qchdman[-x64].vcxproj.
  • Open / add the generated project files in Visual C++ 2010. Only add projects for the same target platform to the same solution: x86 (qmc2-mame, qmc2-arcade, qchdman) vs. x64 (qmc2-mame-x64, qmc2-arcade-x64, qchdman-x64).
  • Only for 64-bit builds you have to adjust a few more things:
    • Change the target platform of all projects to x64! To do this, open the solution's context menu, click Configuration Manager and open the Active solution platform drop-down menu. Click the New item, then select x64 from the platform drop-down (or enter it manually), keep Win32 as the value for Copy settings from and click the OK button, then Close the configuration manager which should show the value x64 for all projects in the Platform column now.
    • Select Windows7.1SDK instead of v100 as Platform Toolset for all projects. To do so, open a project's context menu and click Properties. Then go to Configuration Properties -> General -> Platform Toolset and select Windows7.1SDK from the drop-down menu.
  • Select Build from each project's context menu to create the binary (qmc2-mame.exe, qmc2-arcade.exe or qchdman.exe).
  • After compilation is complete, you'll find the resulting binary in the respective release\ folder (release\, arcade\release\ or tools\qchdman\release\).
  • Select Clean from each project's context menu before attempting a new build!

Installation on Windows

Provided that all necessary DLLs are included in paths pointed to by the PATH environment variable, an installation isn't really required on Windows. As on Linux/UNIX and Mac OS X, you can simply start the executables from the build directory.

If you would like to create binary packages, all you'd have to do is copy the relevant files (binaries/DLLs and data) into a directory which you package as an archive afterwards (using zip or rar, for example). The installation at a user's end would then just be to extract this archive. That's it! There's nothing like a script to support you in that, though.

Besides the VC runtime DLLs (if built with MSVC), the required DLLs include:

imageformats\*.dll
imports\* (recursively, only *.dll and qmldir files)
phonon_backend\phonon_ds94.dll
phonon4.dll
QtCore4.dll
QtDeclarative4.dll
QtGui4.dll
QtNetwork4.dll
QtOpenGL4.dll
QtScript4.dll
QtScriptTools4.dll
QtSql4.dll
QtSvg4.dll
QtTest4.dll
QtWebKit4.dll
QtXml4.dll
QtXmlPatterns4.dll
sqldrivers\qsqlite4.dll
SDL2.dll

MinGW builds additionally need these DLLs (get them from your MSYS2 MinGW installation):

libgcc_s_seh-1.dll
libstdc++-6.dll
libwinpthread-1.dll

Code changes relevant for this document

Version

Category

Type

Description

0.183 Software lists New feature Added support for saving and restoring the last selected software item (per system)
General New feature Added support for system- and software-manuals
0.70 General New feature Added an icon cache database which stores decompressed icon data already mapped to machine IDs in order to speed up the process of loading them
Software lists New feature Added optional automatic state-name adjustment
0.69 ROMAlyzer Renamed feature The former check-sum wizard has been renamed to check-sum finder and its auto-repair functionality has been removed
0.66 General New feature Added a machine list database and custom views
0.65 ROMAlyzer New feature Added support for CHD handling to the collection rebuilder
General New feature Added skipping of emulator identification during start-up when the modification time of the binary hasn't changed
General New feature Added a catver.ini optimizer tool
0.59 General New feature Added optional support for libarchive (compile-time option LIBARCHIVE)
0.58 General New feature Added freely definable additional (custom) artwork classes
General New feature Added individual (parent) fallback settings for built-in and custom artwork classes
0.57 Notes templates Behavior change If an XML query doesn't contain doc($xmlDocument) it's automatically prepended to the query string
General Improvement Added an option to enable/disable the loading animation
ROMAlyzer Improvement Added hash cache and dry run mode to the collection rebuilder
0.56 ROMAlyzer New feature Added hash cache to the check-sum scanner
0.54 General New feature Added support for video snaps
0.53 CLI New feature Added reconfigure (-r) command line option
General Behavior change QMC2 continues loading even if the emulator binary cannot be identified as MAME