Holger's Java API

## com.antelmann.sound
Class JukeBox

    java.lang.Object
      com.antelmann.sound.JukeBox

All Implemented Interfaces:
  SoundPlayer.Listener, EventListener

    @ThirdParty(value="de.vdheide.mp3")
    public class JukeBox

extends Object
implements SoundPlayer.Listener

A simple JukeBox for MP3Player objects.

Simplest usage: after instanciation, add a few URLs or Files to the list and call `playNext()` or `restart()` - that's it. Optionally, you can call `shuffle()` or call `playNext()` anytime when you don't want to wait until the current song is over.

For convenience, this class also provides a main() method, that starts a command line based randomized jukeBox based on a given file or directory containing songs. The file extensions supported by this class are:

    *.mp3, *.au, *.mid, *.aif, *.rmf, *.wav, *.aiff

In addition to the requirements of the MP3Player class, this class also requires the package de.vdheide.mp3 (see: http://www.vdheide.de/).

Since:
  4/11/2002
Author:
  Holger Antelmann
See Also:
  `MP3Player`, `main(String[])`, `JJukeBox`

Nested Class Summary
`static interface` `JukeBox.Listener` JukeBox.Listener listens to events triggered by a JukeBox object.

Constructor Summary
`JukeBox()`

Method Summary
`boolean` `add(File file)` adds a single File to the playlist; returns true only if the file passed the file filter
`boolean` `add(int atIndex, File file)` inserts a single File to the playlist at the specified position; returns true only if the file passed the file filter
`void` `add(int atIndex, URL url)`
`void` `add(URL url)` adds a single URL to the playlist
`void` `addAll(File[] files)` adds those File objects to the playlist that pass the filter
`void` `addAll(URL[] urls)` adds a bunch of URLs to the playlist
`void` `addFromDirectory(File dir)` adds all sound files from the given directory tree recursively.
`void` `addFromFile(File file)` adds all entries in the file to the list.
`void` `addListener(JukeBox.Listener listener)` adds a listener that is notified when a song changes
`void` `clearList()` empties the current playlist
`void` `createSongList(File directory, File fileToWrite, boolean appendToFile)` creates a song list from the given directory and writes it to the given file.
`Object` `getCurrentSound()` returns the sound object currently being played
`ExtensionFileFilter` `getFileFilter()` returns the file filter used to filter entries
`protected MP3Player` `getPlayer()`
`List<Object>` `getPlayList()` returns the curret playlist as an unmodifiable list
`static void` `main(String[] args)` starts a comand line based JukeBox with several options.
`void` `musicStopped(SoundPlayer sound)` called internally; notifies listeners that music stopped and then plays the next song
`Object` `play(int index)` starts to play the song indicated by the index.
`void` `playCurrentSongFromStart()` plays current song from the start
`void` `playLast()` plays the last song in the list
`Object` `playNext()` requests the next song in the current list to be played.
`boolean` `remove(Object listItem)` removes the given item (usually File or URL) from the current play list if it exists
`void` `restart()` selects the first song in the list to be played next
`void` `resume()` resumes the music if previously stopped
`void` `shuffle()` shuffles the list
`int` `size()` returns the size of the playlist
`void` `stop()` stops the music; resume with `resume()`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### JukeBox

    public JukeBox()

Method Detail

### getPlayer

    protected MP3Player getPlayer()

### getFileFilter

    public ExtensionFileFilter getFileFilter()

  returns the file filter used to filter entries

### size

    public int size()

  returns the size of the playlist

### musicStopped

    public void musicStopped(SoundPlayer sound)

  called internally; notifies listeners that music stopped and then plays the next song

  Specified by:
    `musicStopped` in interface `SoundPlayer.Listener`

### play

    public Object play(int index)

  starts to play the song indicated by the index. The index 0 refers to the first song. If the number is negative or larger than the playlist size, the first song is played.

### playNext

    public Object playNext()

  requests the next song in the current list to be played. If a list reached its end, the first song will be selected. If an object in the list is not a valid sound object, it will be skipped and removed from the list.

  Returns:
    the sound object that is played next; null if no valid sound could be retrieved from the list.

### stop

    public void stop()

  stops the music; resume with `resume()`

### resume

    public void resume()

  resumes the music if previously stopped

### playLast

    public void playLast()

  plays the last song in the list

### playCurrentSongFromStart

    public void playCurrentSongFromStart()

  plays current song from the start

### restart

    public void restart()

  selects the first song in the list to be played next

### shuffle

    public void shuffle()

  shuffles the list

### getPlayList

    public List<Object> getPlayList()

  returns the curret playlist as an unmodifiable list

### getCurrentSound

    public Object getCurrentSound()

  returns the sound object currently being played

### clearList

    public void clearList()

  empties the current playlist

### addFromDirectory

    public void addFromDirectory(File dir)

  adds all sound files from the given directory tree recursively. Files will be filtered for supported file extensions. If included entries happen to be non-valid sound objects while loading, they will be skipped and removed from the list.

### addFromFile

    public void addFromFile(File file)
                     throws IOException

  adds all entries in the file to the list. The entries must be File or URL specifications separated by line breaks. File entries will be filtered for the supported file extensions and are furthermore only added to the list if the file exists. If included entries happen to be non-valid sound objects while loading, they will be skipped and removed from the list. Entries with a hash (#) at the beginning of the line will be ignored (i.e. treated as comment).

  Throws:
    `IOException`
  See Also:
    `createSongList(File, File, boolean)`

### addAll

    public void addAll(URL[] urls)

  adds a bunch of URLs to the playlist

### addAll

    public void addAll(File[] files)

  adds those File objects to the playlist that pass the filter

### add

    public void add(URL url)

  adds a single URL to the playlist

### add

    public boolean add(File file)

  adds a single File to the playlist; returns true only if the file passed the file filter

### add

    public boolean add(int atIndex,
                       File file)

  inserts a single File to the playlist at the specified position; returns true only if the file passed the file filter

### add

    public void add(int atIndex,
                    URL url)

### remove

    public boolean remove(Object listItem)

  removes the given item (usually File or URL) from the current play list if it exists

### addListener

    public void addListener(JukeBox.Listener listener)

  adds a listener that is notified when a song changes

### createSongList

    public void createSongList(File directory,
                               File fileToWrite,
                               boolean appendToFile)
                        throws IOException

  creates a song list from the given directory and writes it to the given file.
  The idea is that - once the file is created - you can manually edit the list and then load it back to the JukeBox using `addFromFile()`. This method searches the entire subtree starting from the given directory and filters by the supported sound file extensions.

  Throws:
    `IOException`
  See Also:
    `addFromFile(File)`

### main

    public static void main(String[] args)
                     throws IOException

  starts a comand line based JukeBox with several options. This method first instanciates a JukeBox, then fills the playlist with files from either the given directory or file, and then starts playing. Songs can be skipped by simply pressing 'enter'.

  You can either directly specify a directory as parameter or give a filename by prefixing it with '@'; examples:
  You can also specify a second parameter; if you use "shuffle" as the second parameter, the list is shuffled from the start.

       "java com.antelmann.sound.JukeBox @c:\mylist.txt"
       "java com.antelmann.sound.JukeBox @c:\mylist.txt shuffle"
       "java com.antelmann.sound.JukeBox c:\media\mp3"

  This command line juke box then understands the following commands while running:
  - If you simply press 'enter' (and/or enter anything but the options below), the JukeBox will advance to the next song
  - if you enter "stop" or "s", the music will pause
  - if you enter "resume" or "r", the music will continue if previously stopped
  - if you enter "shuffle", the play list whill be (re-)shuffled
  - if you enter "restart", the play list will begin with the first song in the list
  - if you enter "info" or "i", all known song info will be displayed
  - if you enter "back" or "b", the current song will start from the beginning
  - if you enter "last" or "l", the last song will be played
  - if you enter "exit" or "quit", the JukeBox will quit
  - if you enter "help" or "h", the above commands will be displayed

  Throws:
    `IOException` - if any of the specified files could not be read

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads