HysteriaPlayer: an AVPlayer wrapper that queues and pre-buffers your audio

It is a wrapper, and the wrapper is the point

HysteriaPlayer is described as an Objective-C audio player sitting on top of AVPlayer, and the readme is careful about what it claims: useful basic player functionalities. The two things it lists first are PlayerItem cache management and pre-buffering the next PlayerItem, and those two are the actual contribution over using AVPlayer directly. A plain AVPlayer plays one item at a time and leaves the queue, the caching and the look-ahead to you. This library takes the queue and the look-ahead, so your app hands it a list of URLs through a data source protocol and receives events back through a delegate protocol. On top of that sit the features an audio app needs anyway: supporting both local and remote media, advancing to the next or previous item, player modes for Repeat, RepeatOne and Shuffle, background playback, and extending long time buffering in the background. The stated implementation approach is a few blocks of setup plus delegate implementations in your UIView or UIViewController subclasses to update the interface when a player event changes.

The delegate protocols are the API, and most methods are optional

The whole integration is two protocols. Your playback configurator, which the readme suggests keeping as a standalone model rather than folding into a view controller, implements HysteriaPlayerDelegate and HysteriaPlayerDataSource. The view controller conformances are shown as an interface declaration.

#import "HysteriaPlayer.h"

@interface ViewController : UIViewController <HysteriaPlayerDelegate, HysteriaPlayerDataSource>

The data source side is the smaller of the two, with three optional methods: the number of items, a method that returns a URL for an item at an index with a preBuffer flag, and an asynchronous variant that sets the URL for an item. One of the two URL methods is required. If you do not implement the count method, you have to set the itemsCount property on the player instead. The delegate side carries more optional methods, covering a will-change-at-index notification, a current-item-changed callback that hands you the AVPlayerItem, a rate-changed flag for play and pause, a did-reach-end callback, a preloaded callback carrying a CMTime, a did-fail callback with a HysteriaPlayerFailed identifier and an NSError, and a ready-to-play callback. Every one of them is marked optional, so you implement only the events your interface actually needs.

Buffering resumes itself once five seconds are ready

One behaviour is worth singling out because it is the kind of detail that separates a real player library from a thin wrapper. If the player is suspended because of a buffering issue, it auto-resumes playback when the buffered size reaches five seconds. For a streaming radio app, that is the difference between a track that stutters and one that pauses cleanly and picks up. The delegate list also includes a preloaded callback that passes a CMTime, which is how the interface knows the next item is ready before the current one ends. The README also mentions extending long time buffering in the background, which matters because a suspended app on a flaky connection is exactly when a naive implementation gives up. There is a related known issue for iOS 8 and below with HTTP Live streaming, and the workaround is a property you set the first time the player is initiated, skipEmptySoundPlaying set to YES, because iOS 9 and later are described as fine with no worries.

Setup is a shared instance and two properties

The setup sequence is short. You grab the shared instance, assign your delegate and your data source, and implement the count and URL methods.

...

- (void)setupHyseteriaPlayer
{
    HysteriaPlayer *hysteriaPlayer = [HysteriaPlayer sharedInstance];
    hysteriaPlayer.delegate = self;
    hysteriaPlayer.datasource = self;
}

- (NSUInteger)hysteriaPlayerNumberOfItems
{
    return self.itemsCount;
}

- (NSURL *)hysteriaPlayerURLForItemAtIndex:(NSUInteger)index preBuffer:(BOOL)preBuffer
{
    return [[NSURL alloc] initFileURLWithPath:[localMedias objectAtIndex:index]];
}

The shared instance is also how you reach the query helpers. To get the index of a player item you pass the current item to getHysteriaOrder, and to read the playing item's timescale you call getPlayerTime, which returns a dictionary whose DurationTime and CurrentTime keys you convert to doubles. The player status is read with getHysteriaPlayerStatus, and the switch in the readme covers four cases: unknown, forced pause, buffering and playing. Two lifecycle calls are documented as well. Caching of played items is on by default and can be turned off with enableMemoryCached set to NO, and when you no longer need the instance you call deprecatePlayer and release your reference.

Installing through CocoaPods, with a manual route that needs three frameworks

The CocoaPods route is the documented one, with a Podfile stanza in the readme.

platform :ios, 'x.0'

pod 'HysteriaPlayer',			        '~> x.x.x'
    
end

The manual route is for projects that do not use a package manager, and it has two parts. You drag HysteriaPlayer.m and HysteriaPlayer.h into your project, and then you add CoreMedia.framework, AudioToolbox.framework and AVFoundation.framework to your Link Binary With Libraries. There is also a file to copy, point1sec.mp3, which goes into your Supporting Files, and it exists for a specific reason: it is the ability to play the first player item when your application is resigned active but that first item is still buffering. So a one second silent file is what lets the audio session keep running through a handover. Background playback has its own step in Xcode, where you enable the Audio and AirPlay background mode, found under Project, Capabilities, Background Modes, and the README points out that the background audio mode has to be checked for everything to work.

Tutorials, examples and a licence question

The tutorial series is three parts on the author's blog, covering what the library is for and why, demonstrating how to play remote audio, and then building a simple player interface. The readme flags the version issue itself, saying the demonstrations are on version 2.0.0 and a little bit outdated, because version 2.1.0 modified some of the APIs. The tutorial source code is downloadable from a separate repository, and the project tree also contains an Objective-C example and a Swift example, so both languages are represented in the repository even though the library itself is Objective-C. The README states that all source code is licensed under the MIT License, though the repository listing records the licence as a custom one that GitHub cannot classify, which is worth checking against the LICENSE file before you redistribute anything. The last push to the repository was on 2026-07-19, and the release that went out the same day was 2.3.0, while the two releases before it were 2.2.4 from 2021-02-18 and 2.2.3 from 2020-12-31. The author is Saiday, with GitHub, Twitter and Skype links in the readme.

Editorial conclusion

HysteriaPlayer fits an iOS app that needs a queue of remote or local audio with pre-buffering and background playback without writing the AVPlayer plumbing itself, and it fits a team willing to implement two delegate protocols rather than configure a table of options. It does not fit a new project that wants Swift-first APIs or a maintained dependency, because the source is Objective-C, the version numbers stop in 2021 until 2.3.0, and the README states that version 2.1.0 modified some of the APIs the tutorial series demonstrates. Before you adopt it, read the delegate list rather than the tutorial, pin the exact pod version, and check the background audio mode in your target capabilities, because the library depends on that setting being enabled for playback to continue when the app is not active.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. StreetVoice/HysteriaPlayer on GitHub