FireBee_Setup/tools/mxplay/doc/using.txt

mxPlay User's Manual
====================

1.1 Introduction to mxPlay 1.0.0
--------------------------------

Phew... so it really happend... if you're reading this text it means our
little child called mxPlay is finally released.

Everything started with the one post on our local Atari list for Czech and
Slovak Atari fans, where one guy has complained he isn't able to use great
MegaPlayer under CT60 and that is bad there's no decent player for so many
formats... Some guy on dhs.nu came with the idea to make plugins to FalcAMP,
but it seems FalcAMP development is quite slow (I asked Frost about release
date but he's hunting bugs so no release date is know yet :( ) and even no
plugin API is known...

Final 'ass-kick' was Xi's reply to my comment "Did you see the new GemAce and
GemMod? They looks pretty nice!" in style "Yeah, that's nice, but hell, I
don't want to have nice player for mods, nice player for ace songs and
another nice one for mp3s.. I want one, good looking player with the
playlist!". Oh yes, here it really started.

After some discussion we came to the point "That's damn easy to make it! We
have many free replay routines for various formats, we'll make some lame gem
interface to it, hmm, maybe playlist will be a little bit tricky, but this
could be done in 1-2 weeks!". So, 3 months passed very fast and here you are,
mxPlay player with playlist, skins, plugins, open code and the coolest user
features from the plenty of other players ;)

Maybe you're wondering what the hell we did make on this for about 3 months.
Firstly, I'm democoder. I didn't know nearly anything about GEM. So getting
touch with this kind of programming was a new experience for me. Secondly,
every day we come with new ideas what should we add, my TODO list was (and
still is) full of things to implement...

1.2 Introduction to mxPlay 2.0
------------------------------

Unbelievable, nearly exactly seven years later and I'm updating final bits of
the new version :) Frankly, I considered this project dead as there was very
little of interest from Atari users and I personally don't use Atari for
daily work anymore so I didn't really miss a software like this.

But then again, some magic has happend :) Some time in December I found a
website with Turrican II modules and I realized that I have no clue how to
replay this on my Linux PC. So I googled a little and found the XMP project.
Out of curiosity I read its API documentation and I immediately realized how
easy this would be to port over to our platform.

In about the same time someone asked on dhs about some DSPMOD usage example
and ggn reminded him about mxPlay...

All of this somehow led me to the feeling that I should at least try to make
the project compilable again and perhaps I could try to hack an XMP plugin,
as a proof of concept.

Of course, I coded a simple XMP player in like few hours. So only some tweaks
to Makefile, code a wrapper to the player and we're done, right? Right :)
Immediately as I started mxPlay, I saw a bug here and there and a better way
how to do this and that and ... fuck, I spent 2 months only fixing bugs.
There's very few new features, if any. Only bugfixes, bugfixes, bugfixes. For
some crazy reason I decided also to finish all the remaing plugins (as it's
clear nobody would do that), that led to another delays and frustration.

But, in the end... I've caught really a lot of bugs, improved stability a
lot, I can't understand how the player could work at all before. Now, if you
use only ASAP and XMP plugins, you can even remove the "Super" flag from
mxPlay.prg, it's 100% OS friendly and safe even under memory protection. This
is a thing never seen on Atari before ;-) And bonus - you've got a FireBee
version, too.

Current state is a reasonable compromise between functionality and release
date. Most of the code is still (7 years old!) mess, it made me puke several
times. A lot of things could have been done but I really wanted to get rid of
it. If there's any volunteer ...

1.3 Introduction to mxPlay 2.1
------------------------------

Few weeks after the alpha phase (called 'release' in public ;)) I'm happy to
bring you the la(te)st version of mxPlay. Generally, not much to mention:

- 'Play' initiates playback even if no file is selected on startup
- all dialogs are properly iconified and reopened
- plugin path is now set separately for FireBee and ARAnyM, no more messing
  with copy and rename
- XMP plugin is compiled against the latest version, MTMs and DMFs yet work
- oh and by the way, a plugin for full featured MPEG-1 audio layer I, II and
  III is included ;)

Btw, thanks to the MPG123 plugin I discovered that sample frequency in ARAnyM
is set wrong all the time, i.e. all ASAP and XMP modules I had heard were about
10% slower :))) Oh my.

2. Features
-----------

- modern user interface

- fully skinable GUI

- compatible from the simple TOS to the latest XaAES

- best d&d / va-start / long name support you've ever seen

- memory protection friendly

- multitasking support, windowed dialogs

- universal plugin API which allows you to take any kind of replay routine
  and to adapt it to mxPlay

- it's free!

- open development, anyone can contribute / bugfix

- recursive directory/file adding with autodetection for supported formats

and a lot of more ...

3. Windows
----------

Here you'll find brief description of each mxPlay's window.

3.1 Panel

The heart of mxPlay. You don't need to top the panel, button will be
activated even on untopped panel.

3.1.1 Play

Play the current song. If no song was selected it will be played either the
first file in playlist or the random song (in the case 'Random' button was
activated, see bellow)

3.1.2 Stop

Self-explaining.

3.1.3 Pause

Pause playing. Please note not every plugin supports this function. Click on
this button again to continue playing.

3.1.4 Previous Subsong

Playback must be active to make this work (currently ASAP and SNDH plugin).

3.1.5 Next Subsong

Playback must be active to make this work (currently ASAP and SNDH plugin).

3.1.6 Next Song

Play the next song in the playlist.

If you're at the end of playlist and the 'Repeat' button was activated (see
bellow) as next file will be taken the first one.

If 'Random' button was activated, next song will be choosen randomly.

3.1.7 Previous Song

Play the previous song in the playlist. Please note previous song will be
played even in random mode, no random selection as done in Aniplayer!

3.1.8 Playtime

By clicking on the playtime you change time addition/substraction a la Winamp
or XMMS. Please note that most of the plugins do not support time reporting
so a hardcoded value is used (3 minutes). You can change this in mxplay.inf.

3.1.9 Repeat

Wrap to the begin of playlist when requested for the next song and we're on
the last entry in the playlist.

3.1.10 Random

Activate random song selection. 'Repeat' button has no sense then.

3.1.11 Mute

Mute the playing. This function must be present in the plugin.

3.1.12 Volume Slider

Increase or decrease volume level. It even watches for current sound system
status so you can try to play with volume in some CPX and you will see the
effect :)

3.1.13 Playlist

Open/close playlist.

3.1.14 Module Info

Open/close module info dialog.

3.1.15 Plugin Info

Open/close plugin info dialog.

3.1.16 About

Open/close information about application.

3.2 Playlist

The best playlist for our little Atari :)

3.2.1 Add file

Add file(s) to the playlist. Please note your fileselector has to support
Selectric and/or MagiC/XaAES fileselector protocol to select more than one
file. Except the Selectric and MagiC/XaAES it does Hugo for example.

3.2.2 Add Directory

Add director(y|ies) to the playlist. It's fully recursive operation so, yes,
you can take your music partition and open it in mxPlay! If your fileselector
doesn't allow you to select exact directory, open such directory, clear
"filename" field and press RETURN.

3.2.3 Select All

Select all entries in the playlist. If you press SHIFT key, it will do
inverse operation - i.e. deselecting selected files and vice versa.

3.2.4 Remove

Remove selected files. No stupid questions, so beware.

3.2.5 Load Playlist

Load .m3u file. Yes, that's the file from winamp and others :)

3.2.6 Save Playlist

Save .m3u file.

3.3 Module Info

Here you can find some information about currently played module as provided
by plugin. Enabled (not shaded) arrows mean you can scroll left and/or right
to see the full text (better is to resize window I think ;)

3.4 Plugin Info

Similar to Module Info but you're allowed even enter some values. It could be
simple on/off flag or numerical/text parameter. If there are up and down
arrows you can scroll with them (sorry no resize at this time...)

3.5 About

Simple about dialog. Here you can read the license under which is mxPlay
released and the current version.

4. Keyboard Shortcuts
---------------------

4.1 (SHIFT) CTRL + O

Open (and add to playlist) file(s) or (with SHIFT) director(y|ies).

4.2 CTRL + Q

Quit application.

4.3 SPACE

Pause playing.

4.4 CTRL + P

Start playing.

4.5 CTRL + S

Stop playing.

4.6 (SHIFT) UP ARROW

If in playlist, move up (1 entry or whole page with SHIFT)

4.7 (SHIFT) DOWN ARROW

If in playlist, move down (1 entry or whole page with SHIFT)

4.8 (SHIFT) CTRL + A

Select all entries in the playlist or (with SHIFT) make opaque to the current
state.

4.9 DELETE

Delete selected entries from the playlist.

4.10 INSERT

Activate 'Repeat' button.

4.11 CLR HOME

Activate 'Random' button.

4.12 (SHIFT) TAB

Open/close Module info or (with SHIFT) Plugin info dialog.

4.13 HELP

Open/close About dialog.

4.14 UNDO

Activate 'Mute' button.

4.15 NUM /

Change the current skin. Change is done in realtime but only if there's no
playback.

4.16 NUM (

Play previous song in the playlist.

4.17 NUM )

Play next song in the playlist.

4.18 NUM *

Open/close playlist.

5. Supported protocols
----------------------

5.1 ARGV

You can assign some file type, e.g. *.mp2 to mxPlay and then just click on
the mp2 files and mxPlay will open & play such file. The filename could be
even with spaces, bigger than 8+3 characters etc. Please note, not all
desktops support this, see file BUGS for details.

5.2 VA-START

If you go in the way described in 5.1 you can double-click on the file during
song playing and mxPlay will update its playlist and begin to play this file.

5.3 Drag & Drop

You can take files, directories and even hard disk icons and place it onto
mxPlay, everything will go as you expect! Full support for long names.

6. Thanks
---------

At first I would like to thank to all people who decided to publish their
source codes. Without them there's no mxPlay. So for others - please, support
free software, release your source code - it helps all of us. Very good
example is zView, really good work, Zorro!

Next I have to thank Xi, my never-tired-for-another-bugreport friend ;),
without your usefull hints about application architecture and without your
massive support I doubt I finish mxPlay in this look and functionality.

Also thanks to people on MiNT list, they helped me sometimes when I was in
total dark :)

And at last but not least I have to thank YOU, Atari fan, you're still using
Atari computers!

7. Contact
----------

Don't forget mxPlay is FREE SOFTWARE that means everyone can contribute to
and/or bugfix the current version. If you can't code you can make skins. If
you can't make GEM dialogs, you can test mxPlay, spell-check documentation,
think about new features, ... help is always welcome.

You can reach me 7 days of week at:

miro dot kropacek at gmail dot com

Xi is the author of skins, the most of plugins and he is the very good
beta-tester, you can reach him at:

xi at napri dot sk

... happy playing!