Subject: ANNOUNCE: MPEG::MP3Play 0.09
From: Joern Reder <[email-masked]>
Date: 26 Sep 1999 19:37:13 GMT
Newsgroups: comp.lang.perl.announce,comp.lang.perl.modules

I just uploaded MPEG::MP3Play 0.09 to CPAN.

Its final destination is:

http://www.perl.com/CPAN/modules/by-authors/id/J/JR/JRED/MPEG-MP3Play-0.09.tar.gz

Version 0.09 is a minor bugfix release. Mainly a few 'perl -w' warning
messages are fixed. See the CHANGES section of the attached README for
details. There are no changes to the interface.

NAME
    MPEG::MP3Play - Perl extension for playing back MPEG music

SYNOPSIS
      use MPEG::MP3Play;
      my $mp3 = new MPEG::MP3Play;
      
      $mp3->open ("test.mp3");
      $mp3->play;
      $mp3->message_handler;

DESCRIPTION
    This Perl module enables you to playback MPEG music.

    This README and the documention cover version 0.09 of the
    MPEG::MP3Play module.

PREREQUISITES
    Xaudio SDK

    MPEG::MP3Play is build against the 3.0 version of the Xaudio SDK
    and uses the async interface of the Xaudio library.

    I don't know if older versions will work properly. The SDK is
    not part of this distribution, so get and install it first
    (http://www.xaudio.com/).

    Perl

    I built and tested this module using Perl 5.005_03. It should
    work also with Perl 5.004_04 and above, but I did not test this.
    If someone builds MPEG::MP3Play successfully with other versions
    of Perl, plesase drop me a note.

    Optionally used Perl modules

      samples/play.pl uses Term::ReadKey if it's installed.
      samples/handler.pl requires Term::ReadKey.
      samples/gtk*.pl require Gtk.

DOWNLOADING
    You can download MPEG::MP3Play from any CPAN mirror. You will
    find it in the following directories:

      http://www.perl.com/CPAN/modules/by-module/MPEG/
      http://www.perl.com/CPAN/modules/by-authors/id/J/JR/JRED/

    You'll also find recent information and download links on my
    homepage:

      http://www.netcologne.de/~nc-joernre/

INSTALLATION
    First, generate the Makefile:

      perl Makefile.PL

    You will be prompted for the location of the Xaudio SDK. The
    directory must contain the include and lib subdirectories, where
    the Xaudio header and library files are installed.

      make
      make test
      ./runsample play.pl
      ./runsample handler.pl
      ./runsample gtk.pl
      ./runsample gtkhandler.pl
      ./runsample gtkinherit.pl
      ./runsample synopsis.pl
      make install

SAMPLE SCRIPTS
    There are some small test scripts in the samples directory. You
    can run these scripts before 'make install' with the runsample
    script (or directly with 'perl', after running 'make install').
    For runsample usage: see above.

    All scripts expect a mp3 file 'test.mp3' in the actual
    directory.

    play.pl Textmodus playback. Displays the timecode. Simple volume
            control with '+' and '-' keys.

    handler.pl
            Does generally the same as play.pl, but uses the builtin
            message handler. You'll see, that this solution is much
            more elegant. It *requires* Term::ReadKey.

            This script makes use of the debugging facility and is
            best documented so far.

    gtk.pl  This script demonstrates the usage of MPEG::MP3Play with the
            Gtk module. It produces a simple window with a progress
            bar while playing back the test.mp3 file.

    gtkhandler.pl
            This script does the same as gtk.pl but uses the builtin
            message handler concept instead of implementing message
            handling by itself. Advantage of using the builtin
            message handler: no global variables are necessary
            anymore.

            Because 'runsample' uses '`perl -w'' you'll get a
            warning message here complaining about a subroutine
            redefinition. See the section USING THE BUILTIN MESSAGE
            HANDLER for a discussion about this.

    gtkinherit.pl
            This is 'gtkhandler.pl' but throwing no warnings,
            because it uses subclassing for implementing messages
            handlers.

    synopsis.pl
            This one proves that the usage shown in the SYNOPSIS
            *really* works ;)

BASIC CONCEPT
    The concept of the Xaudio async API is based on forking an extra
    process (or thread) for the MPEG decoding and playing. The
    parent process controls this process by sending and recieving
    messages. This message passing is asynchronous.

    This module interface provides methods for sending common
    messages to the MPEG process, eg. play, pause, stop. Also it
    implements a message handler to process the messages sent back.
    Eg. every message sent to the subprocess will be acknowledged by
    sending back an XA_MSG_NOTIFY_ACK message (or XA_MSG_NOTIFY_NACK
    on error). Error handling must be set up by handling this
    messages.

    You will find detailed information about the interface of
    this module in its POD documentation.

TODO
      - Win32 support
      - support of the full Xaudio API, with input/output
        modules, etc.
      - documentation: more details about the messages
        hashes

    Ideas, code and any help are very appreciated.

BUGS
    Currently there are no known bugs.

PROBLEMS AND REPORTING BUGS
    First check if you're using the most recent version of this
    module, maybe the bug you're about to report is already fixed.
    Also please read the documentation entirely.

    If you find a bug please send me a report. I will fix this as
    soon as possible. You'll make my life easier if you provide the
    following information along with your bugreport:

      - your OS and Perl version (please send me the output
        of 'perl -V')
      - exact version number of the Xaudio development kit
        you're using (including libc version, if this is relevant
        for your OS, e.g. Linux)
      - for bug reports regarding the GTK+ functionality
        I need the version number of your GTK+ library and
        the version number of your Perl Gtk module.

    If you have a solution to fix the bug you're welcome to send me
    a unified context diff of your changes, so I can apply them to
    the trunk. You'll get a credit in the Changes file.

    If you have problems with your soundsystem (you hear nothing, or
    the sound is chopped up) please try to compile the sample
    programs that are part of the Xaudio development kit. Do they
    work properly? If not, this is most likely a problem of your
    sound configuration and not a MPEG::MP3Play issue. Please check
    the Xaudio documentation in this case, before contacting me.
    Thanks.

MPEG::MP3Play APPLICATIONS
    I'm very interested to know, if someone write applications based
    on MPEG::MP3Play. So don't hesitate to send me an email, if you
    like (or not like ;) this module.

TESTED ENVIRONMENTS
    This section will list the environments where this module is
    known to function well:

      - Perl 5.005_03 and Perl 5.004_04, Linux 2.0.33 and
        Linux 2.2.10, Xaudio SDK 3.01 glibc6,
        gtk+ 1.2.3, Perl Gtk 0.5121

      - FreeBSD 3.2 and 3.3. See README.FreeBSD for details
        about building MPEG::MP3Play for this platform.

AUTHOR
    Joern Reder <[email-masked]>

COPYRIGHT
    Copyright (C) 1999 by Joern Reder, All Rights Reserved.

    This library is free software; you can redistribute it and/or
    modify it under the same terms as Perl itself.

    The Xaudio SDK is copyright by MpegTV,LLC. Please refer to the
    LICENSE text published on http://www.xaudio.com/.

SEE ALSO
    perl(1), MPEG::MP3Info.

CHANGES
    Revision history for Perl extension MPEG::MP3Play.

    0.09  Fri Sep 26 1999, joern
	- The error messages thrown on exit of the Gtk+ sample
	  scripts are gone. Thanks to Dermot Musgrove for his
	  suggestions. I added a small chapter about preventing
	  these error messages in the documentation.
	- 'runsample' now uses 'perl -w'. MPEG::MP3Play and
	  all sample scripts should now work without throwing
	  warning messages (except 'gtkhandler.pl' where this
	  is intended).
	- There is a new sample script 'gtkinherit.pl' to demonstrate
	  implementing message handlers by subclassing MPEG::MP3Play
	- README.FreeBSD added, thanks go to Bryan Collins
	  <[email-masked]> for his detailed information
	- 'runsample' is now generated by Makefile.PL to ensure that
	  the correct Perl interpreter is used