v4.0.0

MAJOR RELEASE

Migrating from HXAudio 3.x to HXAudio 4.x

Use this checklist when migrating from 3.x code.

1) Android SDK Baseline

• hxaudio now requires minSdk 21+.
• Any consuming app/module using HXAudio must also set minSdk to at least 21.
• The demo/app is configured for targetSdk 37.
• HXAudio 4.x supports API 21 (Lollipop) and above.
• Support for API 9-20 (including Gingerbread, Honeycomb, Ice Cream Sandwich, Jelly Bean, and KitKat) has been dropped.
• If you require compatibility with API 9-20, use the last HXAudio 3.x.x release.

1.1) Remote URL Playback on Modern Targets

• Prefer https:// media URLs for streaming.
• http:// URLs may fail on targetSdk 37 unless cleartext traffic is explicitly enabled.
• If a legacy endpoint is HTTP-only, add a scoped networkSecurityConfig entry (preferred) or set android:usesCleartextTraffic="true" (broader, less secure).

2) Legacy Compatibility APIs

• HXSound.engines(int) is now a compatibility-only API and is ignored on API 21+.
• HXSound.reinitialize(Context) is retained for manual reset scenarios, but is deprecated for normal usage.

3) Threading Behavior

• Builder play()/resume() operations are now serialized on background executors for safer, non-blocking setup.
• Existing call sites do not need to change, but timing assumptions around immediate setup should rely on listener callbacks (onMusicPrepared) instead of synchronous expectations.

4) Error Handling Enhancements

• HXMusicListener includes a new optional callback:
  • onMusicError(HXMusicItem music, int what, int extra)
• Existing listener implementations remain source-compatible because this method has a default implementation.

5) New Convenience APIs (Optional)

• You can keep builder usage as-is, or adopt additive shortcut methods:
  • HXMusic.play(context, resource)
  • HXMusic.play(context, resource, looped)
  • HXMusic.play(context, url)
  • HXMusic.play(context, url, looped)
  • HXMusic.playGaplessLoop(context, resourceOrUrl)
  • HXSound.play(context, resource)
  • HXSound.play(context, resource, looped)

6) Position Units

• HXMusicBuilder.at(int) uses milliseconds.
• Ensure any prior seconds-based usage is converted (5s -> 5000).

Full Changelog: v3.3.1...v4.0.0

v3.3.1

• HXMusicEngine: Fixed null pointer and illegal state exception error when setting nextMediaPlayer.

v3.3.0

• HXSoundEngine: Fixed issue with sound effects failing to play on certain devices running Android 6.0+ after repeated outputs.

v3.2.9

• HXMusicEngine: Offloaded nextPlayerPreparedListener.onPrepared and nextPlayerCompletionListener.onCompletion to separate threads to minimize potential ANR incidences.

v3.2.8

• HXMusicEngine: Addressed IllegalStateException issues when isPlaying() and setLooping() is called.
• Updated library target SDK to 27. Updated support dependencies on sample app.

3.2.7

• HXMusicEngine:

• pauseMusic(): Added try/catch statement to handle IllegalStateException error that could occur if attempting to pause a MediaPlayer object that has already been released.

v3.2.6

• HXMusicEngine:

• stopMusic(): Added try/catch statement to handle IllegalStateException error that could occur if attempting to stop a MediaPlayer object that has already been released.

v3.2.5

• HXSoundEngine:

• playSoundFx(): Fixed issue with sound looping not working. An incorrect value of 1 was being set when enabled, value has been set to -1.

v3.2.4

• HXMusicEngine:

• initMusicEngine(): Added try/catch statement around currentPlayer.isPlaying() to address any illegal state exception errors.

v3.2.3

• Updated build and target SDK to 26.
• HXAudioPlayerUtils:

• enableSystemSounds(): Added additional exception catches to handle NullPointerException and SecurityException.
• enableSystemSounds(): Marked as deprecated, will be removed in the next major release of HXAudioPlayer.

• HXSoundEngine:

• pauseSounds(): Added additional null pointer check for MediaPlayer object to address crashes seen in reports.