This manual (last modified: <16/01/2009 07:49:23 UTC>) documents Emacs' AlsaPlayer version 0.12 (Gaza Remembered), an Emacs interface to the AlsaPlayer PCM audio player.
Emacs' AlsaPlayer is referred to as EAP (pronounced 'eep') throughout the rest of this manual.
EAP is a project kindly hosted by Gna!.
Includes package download links as well as links to the manual (online, and in various formats).
Mainly for co-developers and project members.
For Subversion users.
For Subversion users.
For Subversion users.
What is a 'jolt' exactly? According to the GNU Collaborative International Dictionary of English, to jolt someone is:
To stun or shock or change the mental state of a person suddenly, as if with a blow; as, the sight of the house on fire jolted him into action; his mother's early death jolted his idyllic happiness. [PJC]
So there we have it.
Imagine, if you will, that you are listening to the elegiac, yet somehow uplifting title track of the album 'Room To Roam' by British folk rock band The Waterboys, and decide that it doesn't quite suit your mood at that particular moment in time. What do you do? Well, let's say you tell your audio player to skip forward to the next song in the current playlist. Now imagine that your audio player is in what's commonly known as 'shuffle mode' and the next song happens to be 'War On War' by American alt country band Wilco. Unless sufficient care is taken (and EAP is the only audio player I know of that takes sufficient care), you will undoubtedly endure a significant jolt to your idyllic happiness.
In short, listen to your music with EAP (with all volume related settings at their default values) and anything you do that would ordinarily result in an abrupt change of volume is preceeded by a gentle volume fade, ensuring that jolts to your idyllic happiness are a thing of the past (power cuts excepted).
Finally, your personal idyllic happiness is part of a wider struggle, namely that of trying to rid our environment of jolts entirely. For most people, Vim is the once popular scouring powder produced by Lever Brothers from 1904 to 1993 and reputedly used by Francis Bacon as a substitute for toothpaste, but for a very few people it is a program that can be used for editing text.
If someone offers you Vim (the program) or makes Vim (the program) available to you in any way, do not accept it! Every attempt to extend Vim (the program) so that it performs adequately as a jolt-eliminating music player has resulted in total and unmitigated failure and each time someone adopts Vim (the program) as their editor of choice the struggle to rid our environment of jolts suffers a significant, demoralising setback; significant because it defeats our stated aim, and demoralising because users of Vim (the program) often develop a strange, irrational loyalty to it, accompanied by an equally unfathomable prejudice towards Emacs. When that happens we have what can only be described as an immovable jolt to contend with.
Persuading users of Vim (the program) to switch to Emacs for the sake of the environment, and not for any other reason, has been known to work in a few well known (though poorly documented) cases.
EAP is an Emacs interface to AlsaPlayer:
AlsaPlayer is a new type of PCM player. It is heavily multi-threaded and tries to excercise the ALSA library and driver quite a bit. It has some very interesting features unique to *nix players. The goal is to create a fully pluggable framework for playback of all sorts of media with the focus on PCM audio data.
Despite the name, AlsaPlayer supports a wide array of different audio output interfaces,
including the one-time GNU/Linux default output interface; OSS. Other output interfaces
supported include Esound, NAS, Sparc, SGI and JACK.
EAP is an Emacs interface to AlsaPlayer so, not surprisingly, it won't work without it.
On a Debian GNU/Linux system a minimal working AlsaPlayer requires that these two packages:
alsaplayer-common
alsaplayer-text
and one of these:
alsaplayer-alsa
alsaplayer-esd
alsaplayer-jack
alsaplayer-nas
alsaplayer-oss
be installed.
Choose the last package according to your audio output interface. AlsaPlayer is designed to work closely with the ALSA system when it's available, i.e., it works perfectly well without it.
Test the text interface by issuing the command:
‘alsaplayer -i text some-audio-file.ogg’
EAP consists of three separate files; eap.el, eap-dired-keybindings.el and eap-autoloads.el. Ensure that all three files are located somehwere in your ‘load-path’. For example, put them in the directory ~/elisp and then add this line to your ~/.emacs:
(add-to-list 'load-path "~/elisp")
Next you must tell EAP the location of your music library, and where you would like to keep your playlists. For example, add these lines to your ~/.emacs:
(setq eap-music-library
"~/my-music-library" ;default value "~/Music"
eap-playlist-library
"~/eap-playlists") ;default value "~/eap-playlist-library"
Important note: Don't make your playlist library a sub-directory of your music library!
EAP will create both directories for you if they don't exist. On the other hand, if you are happy with the default locations you needn't add these lines to your ~/.emacs file at all.
Finally, either add the line:
(require 'eap-autoloads) ;recommended on principle
or
(require 'eap)
to your ~/.emacs file.
The first form defers loading of the package until you actually need it. The second form will causes the package to be loaded at start time every time.
Save your ~/.emacs file and restart Emacs, or issue the command:
M-x load-file RET ~/.emacs RET.
EAP can be started by issuing the command M-x eap from anywhere within Emacs.
Assuming EAP is not already running, when you issue the command M-x eap EAP checks for the presence of this playlist file and if it is found (and has non-zero length) EAP will ask you if you'd like to continue where you left off. Answer positively and EAP will create a playlist from the contents of this file and proceed to play it. If the file is not found (or is of zero length) your music library is displayed in Dired.
If EAP is running when you issue the command M-x eap the EAP buffer (default name ‘*EAP*’) is displayed.
EAP may also be started via one of the three Dired keybindings, all of which can be performed on a single file, a set of marked files, a single directory, or a set of marked directories. I refer to these simply as marked below.
There are two Emacs' AlsaPlayer buffers, called ‘*EAP*’ and ‘*EAP Playlist*’ by default, although these names are customisable. See Customising Emacs' AlsaPlayer.
Exactly the same commands are available in each buffer. See Keys and commands.
If you find killing buffers a hard habit to break you can ensure that AlsaPlayer always quits cleanly (and saves your current playlist) by adding the function ‘eap-always-kill-buffer-cleanly’ to ‘kill-buffer-hook’. This isn't as hard as it sounds. Simply add the following lines to your ~/.emacs:
(add-hook 'kill-buffer-hook
'eap-always-kill-buffer-cleanly)
The same precaution can be taken when killing your Emacs session by adding the function ‘eap-always-kill-emacs-cleanly’ to the list ‘kill-emacs-query-functions’. Simply add these lines to your ~/.emacs as well:
(add-to-list 'kill-emacs-query-functions
'eap-always-kill-emacs-cleanly)
N.B. If EAP is doing its best to avoid jolts to your idyllic happiness
(see Music Without Jolts), which it does by default, then adding these hooks will add
two or three seconds to each operation.
The same set of key commands listed below are available in both EAP buffers; ‘*EAP*’ and ‘*EAP Playlist*’ by default.
| Key | Action | Global command
|
|---|---|---|
| < OR [left] | Previous song | M-x ap<
|
| > OR [right] | Next song | M-x ap>
|
| SPC | Pause/Play | M-x ap.
|
| j | Jump to song | M-x apj
|
| Key | Action | Global command
|
|---|---|---|
| 0 | Volume mute | M-x ap0
|
| - | Volume soft | M-x ap-
|
| = | Volume full | M-x ap=
|
| Key | Action | Global command
|
|---|---|---|
| p | Show current playlist | M-x app
|
| m | Show music library | M-x apm
|
| l | Show playlist library | M-x apl
|
| v | Show current song | M-x apv
|
| s | Add current song to named playlist | M-x aps
|
| i | Toggle fade-in functionality | M-x api
|
| o | Toggle fade-out functionality | M-x apo
|
| Q | Quit EAP | M-x eaq
|
| Key | Action
|
|---|---|
| f | Seek forward
|
| b | Seek backward
|
| [up] | Volume up
|
| [down] | Volume down
|
| k | Keep window small
|
| q | Bury EAP buffers
|
To customise EAP via Emacs' popular Customize framework, issue the command:
M-x customize-group RET eap RET
See Customization.
Please send bug reports, feature requests, hacks, patches and feedback of any sort (good
or bad), to this list.
If volume fade-out functionality is enabled and you pause playback (SPC in an EAP buffer or M-x ap. from anywhere), followed immediately by a command to skip to the next song in the current playlist (> or [right] in an EAP buffer or M-x ap> from anywhere), the volume is not properly restored. Typing = in an EAP buffer, or M-x ap= from anywhere, usually corrects this situation.
Failure to properly restore the volume after a fade-out has been observed in other less easily identifiable situations, but these occasions are thankfully few. If it does happen to you, the same fix (described above) applies.
People are welcome to implement support for other players but the name, Emacs' AlsaPlayer, is here to stay.