README.en

Introduction
============

PMGMusic (or PMG in short) is a GNU/Linux clone of the well-known
music games VOS/CANMusic originally produced by Hanseulsoft. In these
games, notes in a song are represented by falling bricks on the
screen, with each note (do/re/mi/fa/so/la/ti) mapped to one key on the
keyboard. The player is expected to press the corresponding key at the
instant a note reaches a line on the screen, at which time the note
will be played. All these notes, together with the background music,
will form a complete song. The player is scored according to the
accuracy of the keypresses. The songs are stored in MIDI-based *.vos
files, and thousands of official and unofficial songs can be found
online, ranging from beginners' songs to difficult ones requiring 25+
keypresses per second.

The original VOS and CANMusic are closed-source Windows-only
applications, and this GPL program provides a way to play the game
under GNU/Linux. Note that only the "game engine" is included; the
songs (*.vos) files are to be obtained elsewhere, e.g. from an
existing VOS/CANMusic installation. Some annoyances (in the author's
opinion) in the original games have been fixed, and some convenient
features have been added.

Current features
================

* Supports almost all *.vos files from VOS and CANMusic
* Single-player only, and is fully playable
* Basic graphics and sound (ALSA-compatible hardware or software
  synthesizer required, e.g. timidity)
* A brand-new scoring algorithm
* Recording and replaying demos
* Automatic mode, for songs too hard to play yourself
* Sound-only mode, if you just want to leisurely listen to the music
* Speed of falling notes and song tempo adjustable on the command line
* Optionally, the tempo can be adaptively adjusted according to how well
  you are playing

Download
========

PMGMusic is currently only available as source code via Subversion. I
hope I'll find time to package it in the future. In the meantime, the
code in Subversion will probably work.

System Requirements
===================

This game is tested mainly on a 2.4GHz Pentium 4 with integrated
graphics and sound. On slower machines and/or those with poor video
drivers, you may need to turn down pmg's frame rate (see the "fps"
setting in the source code) and/or reduce the quality settings of your
software synthesizer (e.g. timidity).

Only GNU/Linux systems are supported for now due to the ALSA
dependency. You need basic development tools (e.g. binutils,gcc,make)
and development packages for gtk-2.0, libglade-2.0, alsa, openssl, and
popt. In addition, you need an ALSA-compatible hardware or software
MIDI synthesizer, e.g. TiMidity++ (timidity). A good patchset for the
synthesizer, e.g. eawpats, may provide improved sound quality.

Finally, you must have the *.vos files, obtained e.g. from an existing
installation of VOS or CANMusic.

Installation
============

Make sure that you have all the dependencies installed, then simply
type "make" to compile it. No additional installation process is
needed for now.

The default key setting is "zxcv,./" for do,re,mi,fa,so,la,ti,
respectively. To change it, modify the on_main_area_key() function in
pmg.c, and recompile.

Usage
=====

First start timidity if you are using it as the software
synthesizer. The crucial option is "-iA", which makes it accept MIDI
events from ALSA. The other switches are intended for reducing delay
and CPU usage:

TIMIDITY_PCM_NAME=hw timidity -iA -Os -EFresamp=1 -EFreverb=1 -B2,8 -q0/0 -m2000

Now enter the project directory and run pmg:

./pmg /path/to/my/vos/files/foo.vos

If timidity's sequencer port is not 128:0, please specify it using the
-p option. You can see a full list of command-line options by running
"./pmg --help".