Speakup Article Player - JavaScript API

This documentation describes how to use the Speakup Article Player JavaScript API to receive events and control the player state.

Initialization

The API is automatically available through the global $sp object as soon as the player is loaded and initialized.

// Check if the API is ready
if ($sp?.isReady()) {
	// The API is ready to use
	console.log('Speakup Article Player API is ready!');
}

Availability

The $sp object is created immediately when the player loads, but isReady() returns true only after full initialization is complete.

Available Events

`play` Event

Emitted when the player starts playing a track.

$sp.onPlay((eventData) => {
	console.log('Player started playing:', eventData);
});

`pause` Event

Emitted when the player is paused.

$sp.onPause((eventData) => {
	console.log('Player paused:', eventData);
});

`statechange` Event

Emitted when the player play/pause state changes.

Note

This event is not emitted when the current song changes. Use the songchange event for track changes.

$sp.onStateChange((eventData) => {
	console.log('Player state changed (play/pause):', eventData);
});

`songchange` Event

Emitted when the current track changes.

$sp.onSongChange((eventData) => {
	console.log('Song changed:', eventData);
});

`destroy` Event

Emitted just before the player is destroyed. This allows listeners to perform their own cleanup operations.

$sp.onDestroy((eventData) => {
	console.log('Player is being destroyed:', eventData);
	// Perform your cleanup here
});

Event Data Structure

All events (play, pause, songchange) share the same data structure:

{
	type: 'play',              // Event type ('play', 'pause', 'songchange')
	timestamp: 1640995200000,  // Unix timestamp
	currentState: {            // Current player state
		isPlaying: true,
		currentSong: { ... },
		timestamp: 1640995200000
	},
	song: {                    // Current track data
		id: 'podcast-123',
		title: 'Podcast Title',
		articleUrl: 'https://example.com/article',
		author: 'Author Name'
	}
}

State Change Event Data

The statechange event contains both current and previous state:

{
	type: 'statechange',
	timestamp: 1640995200000,
	currentState: {
		isPlaying: true,
		currentSong: { ... },
		timestamp: 1640995200000
	},
	previousState: {
		isPlaying: false,
		currentSong: { ... },
		timestamp: 1640995100000
	}
}

Destroy Event Data

The destroy event contains the final state:

{
	type: 'destroy',
	timestamp: 1640995200000,
	currentState: {
		isPlaying: false,
		currentSong: { ... },
		timestamp: 1640995200000
	}
}

API Methods

Event Listener Methods

Method	Description	Returns
`onPlay(callback)`	Registers a listener for the play event	Function to remove the listener
`onPause(callback)`	Registers a listener for the pause event	Function to remove the listener
`onStateChange(callback)`	Registers a listener for state changes	Function to remove the listener
`onSongChange(callback)`	Registers a listener for track changes	Function to remove the listener
`onDestroy(callback)`	Registers a listener for the destroy event	Function to remove the listener
`on(eventType, callback)`	Generic method to register listeners	Function to remove the listener
`off(eventType, callback)`	Removes a specific listener	-
`removeAllListeners(eventType?)`	Removes all listeners for an event type	-

State Methods

Method	Description	Returns
`getState()`	Returns the current player state	`{ isPlaying, currentSong, timestamp }`
`isPlaying()`	Checks if the player is playing	`boolean`
`getCurrentSong()`	Returns info about the current track	Song object or `null`
`isReady()`	Checks if the API is ready	`boolean`
`destroy()`	Destroys the player and cleans up	-

Method Details