Eduardo Maia


Winamp::Controller - control winamp using Perl via network


  use Winamp::Controller;
  # connect to Winamp
  my $winamp = new Winamp::Controller();
  # clears your playlist

  # each element from @music array is a path to a random mp3 file
  my @music = $winamp->generateplaylist('D:\Media\MP3\Rockabilly',2);
  for (@music)
    # enqueue a file on WinAmp


Winamp::Controller is a module to control winamp using Perl via network or local.


You will need the Winamp plugin "httpQ" on the machine playing the music via winamp. You may find it searching at the winamp website:

Or directly from the author:

After installing this plugin, open Winamp Options >> Preferences. Go to Plugins >> General purpose >> Configure selected plugin. Then you can start the service, define port number, password, and other details.



Creates a new winamp object.

  my $winamp = new Winamp::Controller();

Or you can inform IP, port and password:

  my $winamp = new Winamp::Controller('','4800','mypassword');


Set the host to connect to Winamp httpQ plugin. This is required. Host must be configured under Winamp httpQ settings.



Set the port to connect to Winamp httpQ plugin, usually 4800. Port is a required parameter, and must be configured under Winamp httpQ settings.



Set the password to connect to Winamp httpQ plugin. Password is optional, and should be configured under Winamp httpQ settings.



Get httpQ plugin version, or an error message if it fails.



Change the working direcotry to 'argument'. It returns 1 on success, 0 otherwise.



Clears the contents of the play list. It return 1 on success, 0 otherwise.



Deletes the playlist item at index 'argument'. Note that the index of first music in your playlist is 0. It return 1 on success, 0 otherwise.



Append a file to the playlist. The file must be in the current working directory or pass in the directory along with the filename as the argument. It return 1 on success, 0 otherwise.

  $winamp->enqueuefile('D:\Media\MP3\Joy Division - Love will tear us apart.mp3');


This method generates a playlist without repeating the same music. Better than shuffle option, which always repeats the same music again and again. Better than use Winamp Open Dialog or Windows Explorer to load files, because the music will always be sorted by artist name. Great to broadcast your playlist.

This method receives as argument:

$_[0] = a path to a directory containing your music. It doesn't matter how many subdiretories are inside it, all mp3/wav/wma/ogg files will be loaded to Winamp.

$_[1] = random level, 1 or 2, where:

1 = A playlist will be generated mixing all files from all subdirectories. If you have a subdirectory with dance music mp3 files, other subdirectory with heavy metal, and other with world music, music styles will be mixed.

2 = This method will randomize per subdirectory. So it will play first a directory, then other, then other.

It returns an array containing random paths to mp3 files.

  use Winamp::Controller;
  my $winamp = new Winamp::Controller('','4800','passwordhere');
  my @music = $winamp->generateplaylist('D:\Media\Radio\Music',2);
  for (@music)


Eduardo Maia,


Copyright (C) 2014 by Eduardo Maia

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.16.3 or, at your option, any later version of Perl 5 you may have available.