jlGui

https://github.com/whamtet/basicplayer
Admin
jlGui is a Java music player for the Java platform that supports multiple audio formats including...
Tokens:5,962
Snippets:58
Trust Score:10
License:LGPL-2.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Initialize and Play Audio with BasicPlayer

Source: https://context7.com/whamtet/basicplayer/llms.txt

Demonstrates how to create a `BasicPlayer` instance, open an audio file, start playback, and set volume and pan. Requires `BasicPlayer` and `BasicController` imports.

```java
import javazoom.jlgui.basicplayer.BasicPlayer;
import javazoom.jlgui.basicplayer.BasicController;
import javazoom.jlgui.basicplayer.BasicPlayerException;
import java.io.File;

// Create a new BasicPlayer instance
BasicPlayer player = new BasicPlayer();

// BasicPlayer implements BasicController interface
BasicController control = (BasicController) player;

try {
    // Open an audio file
    control.open(new File("/path/to/music.mp3"));

    // Start playback in a background thread
    control.play();

    // Set volume after play() is called (0.0 to 1.0 scale)
    control.setGain(0.85);

    // Set pan/balance after play() (-1.0 left to +1.0 right)
    control.setPan(0.0);

} catch (BasicPlayerException e) {
    e.printStackTrace();
}
```

--------------------------------

### BasicPlayer Core Initialization

Source: https://context7.com/whamtet/basicplayer/llms.txt

Demonstrates how to instantiate the BasicPlayer and perform initial playback operations.

```APIDOC
## BasicPlayer Initialization

### Description
Initializes the BasicPlayer instance and starts playback of an audio file.

### Method
Java Class Method

### Request Example
BasicPlayer player = new BasicPlayer();
control.open(new File("/path/to/music.mp3"));
control.play();
```

--------------------------------

### Complete Audio Player Implementation in Java

Source: https://context7.com/whamtet/basicplayer/llms.txt

Demonstrates a full audio player with event handling, showing how to integrate BasicPlayer components. Requires BasicPlayer library. Handles file playback, URL streaming, pause/resume, and seeking.

```Java
import javazoom.jlgui.basicplayer.*;
import java.io.File;
import java.util.Map;

public class CompletePlayerExample implements BasicPlayerListener {
    private BasicPlayer player;
    private BasicController controller;

    public CompletePlayerExample() {
        // Initialize player
        player = new BasicPlayer();
        controller = (BasicController) player;

        // Register this class as event listener
        player.addBasicPlayerListener(this);
    }

    public void playFile(String filename) {
        try {
            // Open and play file
            controller.open(new File(filename));
            controller.play();
            controller.setGain(0.85);
            controller.setPan(0.0);
        } catch (BasicPlayerException e) {
            System.err.println("Playback error: " + e.getMessage());
            e.printStackTrace();
        }
    }

    public void playURL(String urlString) {
        try {
            // Stream from URL (e.g., Shoutcast)
            controller.open(new java.net.URL(urlString));
            controller.play();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    public void pauseResume() throws BasicPlayerException {
        int status = player.getStatus();
        if (status == BasicPlayer.PLAYING) {
            controller.pause();
        } else if (status == BasicPlayer.PAUSED) {
            controller.resume();
        }
    }

    public void seekTo(long bytes) throws BasicPlayerException {
        // Seek works best with file sources
        controller.seek(bytes);
    }

    // Event listener implementations
    public void opened(Object stream, Map properties) {
        System.out.println("=== Audio Properties ===");
        for (Object key : properties.keySet()) {
            System.out.println(key + " = " + properties.get(key));
        }
    }

    public void progress(int bytesread, long microseconds, byte[] pcmdata, Map properties) {
        // Update UI progress bar, visualizer, etc.
    }

    public void stateUpdated(BasicPlayerEvent event) {
        System.out.println("State: " + event.toString());
        if (event.getCode() == BasicPlayerEvent.EOM) {
            // Handle end of playback - play next track, etc.
        }
    }

    public void setController(BasicController controller) {
        // Alternative way to get controller reference
    }

    public static void main(String[] args) {
        if (args.length > 0) {
            CompletePlayerExample player = new CompletePlayerExample();
            player.playFile(args[0]);
        }
    }
}
```

--------------------------------

### Configure Audio Output Mixer in Java

Source: https://context7.com/whamtet/basicplayer/llms.txt

Shows how to select a specific audio output device (mixer) for playback with BasicPlayer. Useful for systems with multiple sound cards. Mixer must be set before opening audio.

```Java
import javazoom.jlgui.basicplayer.BasicPlayer;
import java.util.List;

public class MixerSelectionExample {
    public void configureMixer() {
        BasicPlayer player = new BasicPlayer();

        // Get list of available mixers that support audio output
        List<String> mixers = player.getMixers();
        System.out.println("Available audio outputs:");
        for (String mixerName : mixers) {
            System.out.println("  - " + mixerName);
        }

        // Set specific mixer by name (before opening audio)
        if (!mixers.isEmpty()) {
            player.setMixerName(mixers.get(0));
        }

        // Get current mixer name
        String currentMixer = player.getMixerName();
        System.out.println("Using mixer: " + currentMixer);
    }
}
```

--------------------------------

### BasicController Interface for Playback Control

Source: https://context7.com/whamtet/basicplayer/llms.txt

Illustrates the usage of the `BasicController` interface for managing audio playback, including opening files from various sources, controlling playback states (play, pause, resume, stop), seeking, and adjusting volume and pan. Ensure necessary imports for `BasicController`, `BasicPlayerException`, `File`, `URL`, and `InputStream`.

```java
import javazoom.jlgui.basicplayer.BasicController;
import javazoom.jlgui.basicplayer.BasicPlayerException;
import java.io.File;
import java.net.URL;
import java.io.InputStream;

public class PlaybackControlExample {
    private BasicController controller;

    public void demonstrateControls() throws BasicPlayerException {
        // Open from different sources
        controller.open(new File("/path/to/song.mp3"));           // From file
        // controller.open(new URL("http://stream.example.com")); // From URL
        // controller.open(inputStream);                           // From stream

        // Basic playback controls
        controller.play();      // Start playback
        controller.pause();     // Pause playback
        controller.resume();    // Resume from pause
        controller.stop();      // Stop playback completely

        // Seek to position (bytes to skip from start)
        long bytesSkipped = controller.seek(50000);  // Skip ~50KB into file

        // Volume control (linear scale 0.0 to 1.0)
        controller.setGain(0.75);   // 75% volume

        // Pan control (linear scale -1.0 to +1.0)
        controller.setPan(-0.5);    // Slightly left
    }
}
```

--------------------------------

### Implement BasicPlayerListener for Audio Events

Source: https://context7.com/whamtet/basicplayer/llms.txt

Implement this interface to receive notifications for playback events. The 'opened' method provides audio properties like bitrate and duration. The 'progress' method is called during playback with byte read counts, elapsed time, and PCM data. The 'stateUpdated' method handles changes in player state (playing, paused, stopped, etc.). The 'setController' method provides access to the playback controller.

```java
import javazoom.jlgui.basicplayer.BasicPlayerListener;
import javazoom.jlgui.basicplayer.BasicPlayerEvent;
import javazoom.jlgui.basicplayer.BasicController;
import java.util.Map;

public class AudioEventHandler implements BasicPlayerListener {

    /**
     * Called when audio stream is opened and ready to play.
     * Properties include: bitrate, duration, frequency, channels,
     * number of frames, vbr flag, id3v2/id3v1 tags (MP3), comments (Ogg)
     */
    @Override
    public void opened(Object stream, Map properties) {
        System.out.println("Audio opened: " + stream);
        System.out.println("Duration (bytes): " + properties.get("audio.length.bytes"));
        System.out.println("Sample rate: " + properties.get("audio.samplerate.hz"));
        System.out.println("Channels: " + properties.get("audio.channels"));
        System.out.println("Frame size: " + properties.get("audio.framesize.bytes"));
        // For MP3 files with ID3 tags:
        // properties.get("title"), properties.get("author"), etc.
    }

    /**
     * Called multiple times per second during playback with progress info.
     */
    @Override
    public void progress(int bytesread, long microseconds, byte[] pcmdata, Map properties) {
        // bytesread: position in encoded stream
        // microseconds: elapsed time (resets after seek!)
        // pcmdata: raw PCM samples for visualization/analysis
        System.out.println("Position: " + bytesread + " bytes, " +
                          (microseconds / 1000000.0) + " seconds");
    }

    /**
     * Called when player state changes (opened, playing, paused, stopped, etc.)
     */
    @Override
    public void stateUpdated(BasicPlayerEvent event) {
        switch (event.getCode()) {
            case BasicPlayerEvent.OPENING:
                System.out.println("Opening: " + event.getDescription());
                break;
            case BasicPlayerEvent.OPENED:
                System.out.println("Opened at position: " + event.getPosition());
                break;
            case BasicPlayerEvent.PLAYING:
                System.out.println("Playback started");
                break;
            case BasicPlayerEvent.PAUSED:
                System.out.println("Playback paused");
                break;
            case BasicPlayerEvent.RESUMED:
                System.out.println("Playback resumed");
                break;
            case BasicPlayerEvent.STOPPED:
                System.out.println("Playback stopped");
                break;
            case BasicPlayerEvent.SEEKING:
                System.out.println("Seeking...");
                break;
            case BasicPlayerEvent.SEEKED:
                System.out.println("Seek completed");
                break;
            case BasicPlayerEvent.EOM:
                System.out.println("End of media reached");
                break;
            case BasicPlayerEvent.GAIN:
                System.out.println("Volume changed to: " + event.getValue());
                break;
            case BasicPlayerEvent.PAN:
                System.out.println("Pan changed to: " + event.getValue());
                break;
        }
    }

    /**
     * Provides handle to control playback from listener
     */
    @Override
    public void setController(BasicController controller) {
        // Store controller reference for later use
    }
}
```

--------------------------------

### Access and Adjust Equalizer Settings

Source: https://context7.com/whamtet/basicplayer/llms.txt

Utilize the integrated JEQ library to access and modify the 10-band equalizer settings after the audio line has been opened. Band frequencies are pre-defined, and values can be set for each band.

```java
import javazoom.jlgui.basicplayer.BasicPlayer;
import davaguine.jeq.core.IIRControls;
import java.io.File;

public class EqualizerExample {
    public void configureEqualizer() throws Exception {
        BasicPlayer player = new BasicPlayer();
        player.open(new File("/path/to/music.mp3"));

        // Get equalizer controls (10 bands)
        IIRControls eq = player.getEQ();

        // Adjust individual bands
        // Band frequencies typically: 31Hz, 62Hz, 125Hz, 250Hz, 500Hz, 
        //                             1kHz, 2kHz, 4kHz, 8kHz, 16kHz
        // eq.setBandValue(band, value);

        player.play();
    }
}
```

--------------------------------

### Configure Audio Buffer and Thread Sleep Time

Source: https://context7.com/whamtet/basicplayer/llms.txt

Tune audio latency and CPU usage by setting the SourceDataLine buffer size and the thread sleep interval. A minimum buffer size of 10000 bytes is recommended. A sleep time of -1 indicates no sleep.

```java
import javazoom.jlgui.basicplayer.BasicPlayer;

public class BufferConfigExample {
    public void configurePlayer() {
        BasicPlayer player = new BasicPlayer();

        // Set SourceDataLine buffer size (affects audio latency)
        // Minimum recommended: 10000 bytes
        // -1 = use maximum available buffer
        player.setLineBufferSize(16384);

        // Get configured buffer size
        int configuredSize = player.getLineBufferSize();
        System.out.println("Configured buffer: " + configuredSize);

        // After audio is opened, get actual buffer size
        // int actualSize = player.getLineCurrentBufferSize();

        // Set thread sleep time for CPU optimization
        // -1 = no sleep (default, higher CPU usage)
        // Positive value = milliseconds to sleep between buffer writes
        player.setSleepTime(10);  // 10ms sleep

        // Get current sleep time
        long sleepTime = player.getSleepTime();
        System.out.println("Thread sleep: " + sleepTime + "ms");
    }
}
```

--------------------------------

### BasicController Playback API

Source: https://context7.com/whamtet/basicplayer/llms.txt

Details the methods available in the BasicController interface for controlling audio playback state and properties.

```APIDOC
## BasicController Playback API

### Description
Defines the interface for controlling audio playback, including play, pause, resume, stop, seek, gain, and pan.

### Methods
- **open(Object source)**: Opens audio from File, URL, or InputStream.
- **play()**: Starts playback.
- **pause()**: Pauses playback.
- **resume()**: Resumes playback.
- **stop()**: Stops playback.
- **seek(long bytes)**: Seeks to a specific byte position.
- **setGain(double gain)**: Sets volume (0.0 to 1.0).
- **setPan(double pan)**: Sets balance (-1.0 to 1.0).
```

--------------------------------

### Control Audio Gain and Pan

Source: https://context7.com/whamtet/basicplayer/llms.txt

Access and modify volume (gain) and stereo balance (pan) after opening the audio line. Gain is set on a linear scale from 0.0 to 1.0, while pan ranges from -1.0 (left) to +1.0 (right).

```java
import javazoom.jlgui.basicplayer.BasicPlayer;
import javazoom.jlgui.basicplayer.BasicPlayerException;
import java.io.File;

public class AudioControlsExample {
    public void demonstrateControls() throws BasicPlayerException {
        BasicPlayer player = new BasicPlayer();
        player.open(new File("/path/to/audio.mp3"));
        player.play();

        // Check if gain control is supported
        if (player.hasGainControl()) {
            System.out.println("Gain control supported");
            System.out.println("  Minimum gain: " + player.getMinimumGain() + " dB");
            System.out.println("  Maximum gain: " + player.getMaximumGain() + " dB");
            System.out.println("  Current gain: " + player.getGainValue() + " dB");

            // Set gain using linear scale (0.0 to 1.0)
            player.setGain(0.5);  // 50% volume
        }

        // Check if pan control is supported
        if (player.hasPanControl()) {
            System.out.println("Pan control supported");
            System.out.println("  Precision: " + player.getPrecision());
            System.out.println("  Current pan: " + player.getPan());

            // Set pan (-1.0 = full left, 0.0 = center, +1.0 = full right)
            player.setPan(-0.3);  // Slightly to the left
        }

        // Mute control
        player.setMute(true);   // Mute audio
        player.setMute(false);  // Unmute audio
        player.toggleMute();    // Toggle mute state
    }
}
```

--------------------------------

### Check Player Status

Source: https://context7.com/whamtet/basicplayer/llms.txt

Query the current state of the BasicPlayer using predefined status constants. This allows applications to determine if the player is unknown, opened, playing, paused, stopped, or seeking.

```java
import javazoom.jlgui.basicplayer.BasicPlayer;

public class StatusExample {
    public void checkStatus(BasicPlayer player) {
        int status = player.getStatus();

        switch (status) {
            case BasicPlayer.UNKNOWN:
                System.out.println("Player not initialized");
                break;
            case BasicPlayer.OPENED:
                System.out.println("Audio file opened, ready to play");
                break;
            case BasicPlayer.PLAYING:
                System.out.println("Currently playing");
                break;
            case BasicPlayer.PAUSED:
                System.out.println("Playback paused");
                break;
            case BasicPlayer.STOPPED:
                System.out.println("Playback stopped");
                break;
            case BasicPlayer.SEEKING:
                System.out.println("Currently seeking");
                break;
        }
    }
}
```
Tokens:
Raw