MPT OHM 1.19.01 AVAILABLE!

[Harbinger]

For rookies and veterans alike, anyone who wants to know how to use ModPlug Tracker and get to learn its features!

Note: The OHM is outdated!
Everything you need can be found in the help file that comes with every OpenMPT installation, or in our wiki!

The manual is about 195 pages, 13MB thick, and in PDF format. It corrects problems with the 1.00 OHM, and reflects all of the improvements in ModPlug Tracker 1.19.1. Like the first version, the PDF is divided between a "beginner's" section and a Reference section. There are descriptive Appendices for Channel FX commands among other things, and an improved index at the end (which i suggest printing so you don't have to constantly go back and forth between the index and the info you're looking for). The file is rife with images and they've been updated where necessary to reflect new designs in ModPlug's appearance. There are also scores of hyperlinks to jump to other areas of the OHM for more info on the subject you're reading.

If you need to print out some quick tables, and you don't want to mousewheel thru the entire PDF, this listing should help:

Code Select Expand


Channel FX, IT format.....................166-171
Channel FX, MOD format....................154-156
Channel FX, MPTM format...................166-172
Channel FX, S3M format....................161-165
Channel FX, XM format.....................157-160
Envelope Loops + Sample Loops..................25
Index.....................................187-195
IT Compatibility differences...................49
Keyboard Shortcut descriptions............177-186
MIDI, Input, Enabling.........................144
MIDI, Output, Enabling........................145
Note FX commands (IT-type and XM only)........174
Note Stops used by different tracks............34
Plugins, known issues.......................64-65
Plugins, loading............................54-57
Tempo Modes....................................13
XM Compatibility differences...................50


If you want to know what changes were made since OHM 1.00, read the next post.

The source documents (for those who are or will be working on their own version of the OHM) will be made available soon at sourceforge, but you can still get the old 1.00 docs if you want. I'll notify you here when the source docs for 1.19.01 are ready. There are a few more pages of research and some other interesting guides.

UPCOMING:
Though i'm not making any promises as to how long, i'm working on the HelpFile (html) version of the OHM, which will be be alot more dynamic and less "stiff." If you've already started working on your own attempt at a Help document, and you want to collaborate, let me know by PM. I've found a couple of nice applications that will be of great assistance, and dividing the work might make the project get done faster.

Feel free to critique the OHM, let me know where it fails, where it's helped, or simply make some comments, here in this thread. Understand, the OHM's syntax is a little looser than formal, but a little more technical than schoolbook. The layout was meant to be more efficient than open, and the text as speed-readable as possible (serifs are speedbumps!). Grammar Nazis will be tolerated but ignored, while constructive criticism (what's wrong and what's a good way to fix it) will always be given a second look.

Thanks to Jojo, for his intermittent and yet tireless work on making this program better, as a lot of trackers both new and has-been have relied on his wizardry to see ModPlug grow. I also thank him for the wealth of info that springs eternal from his pulsating brain...

Thanks to LPChip, as always, for providing the framework where new users can find and upload MPT, and for hosting the website where we can all exchange.

And thanks to whomever else deserves it (you know who you are!).

Keep in mind that the OHM has been superseded by the OpenMPT wiki. If you still want to download it, open the OHM directly here. To download, right-click and choose "Save Target As".

[Harbinger]

MPT OHM Edit History

Red = Major additions
Blue = Major improvements

1.19
-- OHM versions numbers will now match MPT version numbers

  GENERAL
-- Reconfigured the source position. The OHM is now kept in the directory C:\Program Files\OpenMPT OHM, and the images folder is kept inside that. (The PDF can go anywhere.)
-- New images are now going to be in non-interlaced PNG format.
-- Improved index entries, hyperlinks, and bookmarks. Now all hyperlinks will jump to the correct location in the OHM (hopefully).
-- Converted all quotes to smart quotes, and apostrophes to smart apostrophes.
-- Terms that were put in quotes are now put into boldface instead, if they denote a term that might be found in the glossary.
-- Various format updates.
-- Typographical corrections and miscellaneous edits for clarity.
-- Resizes of many images on-page.

  INTRODUCTION
-- Reformatted the Features list, made grammar corrections, and added/changed descriptions of MPT features.
-- Updated the Installation procedures, including adding a new section for Portable Mode, with a complete how-to on making MPT completely portable.

  BASIC OPTIONS
-- Corrected the location of where the configuration files for MPT are kept in non-portable mode.
-- Updated the Color Options graphic and the corresponding Colors menu.
-- Updated the Keyboard Options graphic.
-- Reformatted the Tempo Mode table.

  INSTRUMENTS
-- Moved Sample assignment paragraph to Instrument section.

  PATTERNS
-- Added graphic to show parts of Order List, and rewrote the corresponding section to clarify features and new functions.
-- Added mention of mousewheel capability in Pattern page.
-- Added mention of Record Note Off switch in Record Select section.

  MACROS
-- Added paragraph to better describe how macros are universally applied.
-- Completely overhauled the section on using macros to control sample filtering. The new section is very detailed, contains new graphics, and shows various ways to use macros to change the channel filter mode and the resonance and cutoff for sample playback.

  FILE FORMATS/COMPATIBILITY
-- Updated the Compatilibility Mode graphic and updated section.
-- Updated Compatible Mode tables.
-- Updated ITP description and limitations.

  VSTS
-- Added mention of "problematic" plugins.
-- Added section on loading/saving VSTi banks with Chainer.

  KNOWN ISSUES
-- Added more VSTi's to the listing, including Roland's "Orchestral", Angular Momentum's "Freehand", and Farbrausch's "V2" plugins.
-- Emended and amended others, such as DSK and MDA VSTs.

  EPILOGUE
-- Added special dedication to the Contributors List.

  REFERENCE: TABS
-- Updated Initial Global Volume and Initial Sample Volume settings in the General page.
-- Updated and expanded the Order List settings, including what happens with various mouseclicks and the new Margin setting.
-- Added a section detailing the Channel Headers in the PE, including the functions of various mouseclicks.
-- Added a section on Selecting Data, which was upgraded when the Row Selection feature was added.
-- Updated the Samples page graphic.
-- Updated the Open Sample icon description.
-- Added the new Crossfade Sample icon description.
-- Added mention of sample quantization in the Sample Display description.
-- Added mention of Global Volume in relation to plugins in the Instruments page.
-- Added limitations to Fade Out and Instrument Pan settings based on track type.
-- Updated the Plugin assignment feature in the Instruments page.
-- Changed Comments page graphic and expanded the description of the Comments page.

  REFERENCE: DIALOGS
-- Reordered many of the dialog descriptions for better layout.
-- Added description of new Edit History dialog.
   SETUP OPTIONS
-- Added mention of new keybindings file storage.
-- Updated Keyboard Options graphic to show new layout and rewrote section accordingly.
-- Updated Colors Options graphic, the Colors menu, and rewrote the section accordingly. Also added a complete description of the menu entries and what the colors affect in MPT.
   SONG PROPERTIES
-- Updated graphic.
-- Rewrote Old Effects description.
-- Added the new Compatible Mode Mix Format description.
-- Added descriptions of the flags.
   PATTERN PROPERTIES
-- Updated graphic and rewrote section accordingly.
   TUNINGS
-- Corrected Finetune steps description.
   MIDI MAP
-- Corrected Capture and MIDI message descriptions.
   FIND & REPLACE
-- Updated graphic and rewrote section accordingly.
-- Added mention of Replace vs. Undo.
   SCALE POINTS
-- Corrected effect of negative numbers in these fields.

  REFERENCE: MENUS
   FILE
-- Added mention of Compatible Mix Level when choosing New.
-- Updated graphic.
   EDIT
-- Added mention of changing default UNDO handling.
-- Updated graphic.
   VIEW
-- Updated the graphics and added descriptions of the new menu items.
   HELP
-- Updated graphica and rewrote section accordingly.

  REFERENCE: CONTEXTUAL MENUS
   SAMPLE DISPLAY
-- Added new graphic to show the different contextual menus with and without a waveform selection. Rewrote the section accordingly, including the new Quick Fade feature.
   PATTERN EDITOR
-- Updated graphic and rewrote section accordingly. Many changes have occurred to this contextual menu.
   ORDER LIST
-- Updated graphic and rewrote section accordingly, including the Sequences submenu, the Cut & Paste functions, and the Rendering feature.

   REFERENCE: AUDIO PROCESSING
-- Added mention of Global Volume in relation to plugins in the Instruments page.


-- Added a new Reference Chapter on ModPlug's external files.

  APPENDIX: FX COMMANDS
-- Reformatted the layout, including better fonts and better page control.
-- Moved the ModPlug Player Loop anomaly mention to the introductory section.
-- Hopefully all the command index links work properly.
-- Reordered the category order to volume commands, then pitch, pan, instrument/sample, channel, and pattern.
-- Removed updated index entries in the command description tables as they screw them up when saving (OO bug). Index entries point to the category heading instead, which are no longer part of the table.

  APPENDIX: KEYBOARD SHORTCUTS
-- Updated applicable tables.

  INDEX
-- Added many more and updated new entry points, cleaned up and made more efficacious the index entries, and generally made it more rookie-friendly.
-- Added a symbols section at the beginning of the index for not-so-intuitive symbols encountered in MPT.

1.00
--Initial release, for MPT build 1.18.3

[Saga Musix]

Thanks for keeping the OHM alive...

Feel free to critique the OHM, let me know where it fails

Sadly, it fails right on page 3, with a rather big mistake that might hinder people from actually accessing the paths described:

C:\My Computer\[My Hard Disk]\Documents and Settings\[User]\Application Data\%APPDATA%\OpenMPT.

This is wrong in many ways. First off, there is no folder "My Computer" on C:\. Furthermore, %APPDATA% is a shortcut to the Application Data folder that is independent of the Operating System used, i.e. it works both on WinXP (where it is substituted by C:\Documents and Settings\[User]\Application Data in most cases) and Vista/7 (where it is substituted by C:\Users\[User]\AppData\Roaming\ in most cases). So the correct path is %APPDATA%\OpenMPT\ - nothing more, nothing less. You can type this right in the location bar and it will be resolved automatically on all Windows versions.

Concerning mixing modes (p.96)...
- Compatible mix levels are always enabled for MOD/S3M, not Original mixmodes.
- Also, the description for compatible mix mode is wrong. It is neither standardized, nor does it disable any hacks. Mix modes only alter panning/volume levels. Effectively, that means simply that all volumes in this mixmode are as loud as in Schism Tracker, but this only concerns global amplifaction, nothing else. Plus, it disables soft panning because it will generate a wrong stereo impression. It does explicitely not deal with out-of-range notes or anything.

Pattern attributes (p.107)...

For MPTM tracks, you can enable per-pattern Time Signatures by setting the "Override" checkbox. Then enter the rows-per-beat and rows-per-measure values that you want to apply to this measure only.

I suppose the second-to-last word is supposed to be "pattern".

Sample stuff (p.133)...

For a stereo waveform, when this technique is used for one channel instead of both, it's called phase inversion.

This is a nice information but it might be misleading in this context, because currently you cannot chose which channel(s) to apply inversion to - all channels are inverted if you use this function.

Color setup (p.147)...

If a color line is invalid or missing, ModPlug substitutes an internal default setting.

MPT cannot tell if a line is "invalid". It will use default values if a line is missing, but if a line doesn't make sense (f.e. "Color00=Red"), it is generally not predictable (or at least I won't explain) what it will do with that value.

Macros (p.38)...

You can also use the \xx command instead of Zxx to apply a smooth transition between macro values. However, macro slide commands do not slide plugin or MIDI values.

The last sentence is imprecise/wrong. Smooth slides can be applied to all internal devices (that includes the resonant filter and plugin parameters, or in general any macro that starts with F0F0 or F0F1), but it can not be applied to external macros (macros that don't start with F0F0 or F0F1), as MPT cannot know the meaning of the external message and what its previous state was.

Use this setting if you wish to control resonance but you don't need a high degree of detail, or if you have other tracks that can only use this range

You might confuse people with the last part of that sentence. Why should a "track" not be able to "use" the full resonance range?

This Fixed Macro extends the cutoff control to the entire Zxx range, allowing for superfine frequency cutoff control.

The cutoff filter always has a maximum resolution of 7 Bit. There is no "superfine" frequency control mode with higher detail. You don't get anything from using both Z00-Z7F and Z80-ZFF for controlling cutoff. Both ranges will control the cutoff frequency with the same granularity.

Z90 or Z91 switches to LP shelf mode, and Z92 or Z93 forces the HP shelf

Please revise your terminology here. MPT doesn't have a shelf filter. A shelf filter is commonly a different type of filter (one that leaves one side of the cutoff frequency untouched and and highers/lowers the other side of the filter by a specified amount - with a normal cutoff filter, this specified amount is infinity).

And while we're at terminology... Your use of the word "cache" is very unfortunate. Commonly, a cache is a temporary storage that is not under the control of the user, i.e. the user cannot decide what stays for how long in the cache, and it can usually be deleted without any consequences, as it is generally just a structure to increase the execution speed of a program. So if you call the undo memory an undo "cache", that would imply that OpenMPT could decide at any point to remove your undo points, and not after it reached its 1000 undo points limit. Same goes f.e. for the "store" button in the channel manager - this is a memory, not cache, since it will remember the setting as long as you wish, and not for a random amount of time.
Another example, that is both wrong in terminology and in the actual content:

Plugin List: Shows all plugins that have been loaded into MPT's cache (this list is kept within the file plugin.cache).

The plugin list is not a cache, i.e. it's not temporary. However, the file plugin.cache is indeed a cache, meaning that if you delete this file, your plugin list in OpenMPT will not be emptied because the actual plugin list is stored in mptrack.ini in the VST section. If you delete this section in mptrack.ini, your plugin list will be lost - because it's not a cache, but a permanent storage. plugin.cache, on the other hand, is just a file to speed up the startup process of OpenMPT, and its existence is not crucial to the program.

[Rakib]

Great work as usual. Will be reading the manual later today.

[Harbinger]

Thanks for the eagle-eye, Jojo. I'm working on the CHM version (which is coming along quite nicely and quickly), so i will incorporate your fixes.

Concerning the very first subject....

I have never seen the term %APPDATA% until you brought it up in this forum, nor have i seen it anywhere else in my travels on the web or in my computer. I don't doubt what you say, but it's not as universal as you seem to think. I'm going to guess that you have a more up-to-date OS than i do, and so you see this, or can access it, or more readily available to you.

But since it is not first-of-all universally seen and second-of-all intuitive, this will always remain a secondary way in the OHM  to access this HD location. The info i presented is what i see on my computer. I navigate through it using Windows Explorer's folder tree, and i'm sure this is the most basic way to do it. But if it can done the hard way (mine), it can be done the easy way (yours).

I will, however, keep the mention there and correct this path info. (You weren't very clear the first time you told me about it. )

Other notes:

Compatible Mode: I thought the whole purpose of COMPATIBLE mode was compatibility with the standard version (of IT, XM, etc.). Are you saying that Compatibility Mode is not true compatible mode? Perhaps it should be called something else...

"Cache": Just a term to denote an uneditable and temporary storage place for MPT's values that it needs and doesn't want to dump until termination. Suggest another term if you have one; i don't think the average user is concerned about the technical connotations that most programmers get (that the average user wouldn't).

[Saga Musix]

I'm going to guess that you have a more up-to-date OS than i do, and so you see this, or can access it, or more readily available to you.

No, %APPDATA% as a variable is pretty much invisible to anyone how doesn't know about it, as paths are never displayed like that in Explorer (or anywhere else, for that matter). However, it does universally work as said, and if you do not want to refer to this variable and still want to be universal, you have to distinguish between Windows 2000/XP (where the path would by My Computer -> Windows Drive (mostly C:) -> Documents and Settings -> User Name -> Application Data) and Windows Vista / 7 (My Computer -> Windows Drive (mostly C:) -> Users -> User Name -> AppData -> Roaming) - Your method has the severe disadvantage that "AppData" (and I think also "Application Data" on Win2k/XP) is a hidden folder, meaning that your average user won't even see it!

To save users from all this hassle, a link to the settings folder is actually created during installation (and is also provided by means of a .bat file if the user choses the .ZIP version instead), so I'd recommend people to use that instead of explaining what %APPDATA% is or how to reach the paths on two different Operating Systems.

Compatible Mode: I thought the whole purpose of COMPATIBLE mode was compatibility with the standard version (of IT, XM, etc.). Are you saying that Compatibility Mode is not true compatible mode? Perhaps it should be called something else...

You have to distinguish between compatible mixmode and compatible playback mode. The passage I was referring to is about the mixmode. There is no compatible mixmode that is truly compatible to every old tracker simply because they all had a different way of how to generate the final output (think of the boost settings in FT2, or the mixing volume in ST3 and IT...), however the new "Compatible" mixmode uses the same volume levels as Schism Tracker, which make most modules sound good across various trackers. True compatibility cannot be achieved here.
On the other hand, the compatible playback mode flag (visible as a checkbox in IT/MPTM/XM format) is the one you have been documenthing for a long time already, i.e. the thing that changes how various effects behave. This has nothing to do with mix levels, though.

Suggest another term if you have one

The word "memory" would be the most fitting in most cases. I bet most people would rather understand what a memory is than what a cache is (have you ever programmed your stereo? doesn't it have "memory" buttons for EQ, radio stations, whatever? ).

[Harbinger]

Fair enough

[Rakib]

One another topic that could be nice to add:
How to compile the source.

[Saga Musix]

I don't think that belongs in the OHM (in the new wiki, which should go online at some point, there would be a place for stuff like that), but instructions on how to compile the code can be found in the file README that can be found in the repository.

[jmichae3]

tobybear.de's vst2mid plugin mentioned on p. 145  is no longer available, so there is mo more midi output for openmpt(?)

[Saga Musix]

Of course it's still available. I've even recently mailed the author about a bug in the plugin and he responded.

[jmkz]

Clarifications such explanation of %APPDATA%\OpenMPT (reply #5) should be ported into wiki in a appendix section or somewhere, basing me on Jojo's statements (and yes, it's not known by majority of users).

[Saga Musix]

Is it just me or are a multitude of internal links in the OHM not working at all? I tried the latest version of SumatraPDF of Windows and Adobe Reader on Linux but both failed to follow many links in the OHM. This doesn't make the document very easy to read, especially since many of the links are practically like a mystery meat navigation. "Click here for more information"? Fine, but the "here" link isn't working, and its caption isn't even telling me what I should look for...

[jmkz]

Is it just me or are a multitude of internal links in the OHM not working at all? I tried the latest version of SumatraPDF of Windows and Adobe Reader on Linux but both failed to follow many links in the OHM. This doesn't make the document very easy to read, especially since many of the links are practically like a mystery meat navigation. "Click here for more information"? Fine, but the "here" link isn't working, and its caption isn't even telling me what I should look for...

Yep, it only works (in some cases) for OHM source files, and only if were located at certain directory in %ProgramFiles%\OpenMPT folder. There's a lot of this that should be corrected. I have done a list of few things but I left them in another PC.

[Harbinger]

This is one of the primary reasons i wanted to make a CHM -- relative hyperlinks. In case you forgot my mentioning it, OpenOffice does not make it easy or apparent to create relative hyperlinks (links that direct you to another page in relation to the document itself rather than the absolute path described on the computer). This was the biggest bugaboo about using OO that i never had a problem with in WORD.

The upcoming CHM and hopefully the Wikipage will resolve that problem, and give them an advantage over the OHM format (built on OO docs). Ideally, any time a new user has a question about a function, feature, or meaning, they can click on the word and be redirected to the page that addresses the question directly.