Latest 2.2.2
License MIT
Platforms ios 6.0, osx 10.9, requires ARC
Frameworks CoreMedia, AudioToolbox, AVFoundation

Hysteria Player

HysteriaPlayer provides useful basic player functionalities.

It provides:

  • PlayerItem cache management.
  • Pre-buffer next PlayerItem.


  • Supporting both local and remote media.
  • Setting up HysteriaPlayer with few blocks, implementing delegates in your UIView and UIViewController subclasses to update UI when player event changed.
  • Ability to advance next/previous item.
  • If player suspended bacause of buffering issue, auto-resume the playback when buffered size reached 5 secs.
  • Background playable. (check the background audio mode then everything works)
  • Using getHysteriaOrder: to get the index of your PlayerItems.
  • Extends long time buffering in background.
  • Player modes support: Repeat, RepeatOne, Shuffle.


In part 0, what we want? why HysteriaPlayer?

In part 1, demonstrating how to play remote audios with HysteriaPlayer. (version 2.0.0, a little bit outdated. version 2.1.0 modified some APIs)

In part 2, making a simple player user interface.

You can download tutorial source code here



If you using CocoaPods, it’s easy to install HysteriaPlayer.


platform :ios, 'x.0'

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


Manually install

Import library to your project

Drag HysteriaPlayer.m, HysteriaPlayer.h to your project.

Add Frameworks

Add CoreMedia.framework, AudioToolbox.framework and AVFoundation.framework to your Link Binary With Libraries.

Copy provided point1sec.mp3 file to your Supporting Files

Ability to play the first PlayerItem when your application is resigned active but first PlayerItem is still buffering.

Background modes for audio playback

Xcode providing GUI checkbox to enable various background modes. Enable Audio and AirPlay, you can find this section from Project -> Capabilities -> Background Modes.

How to use

Delegate, DataSource

Implement HysteriaPlayerDelegate and HysteriaPlayerDataSource in your own playback configurator model. (It can be an UIViewController subclass as well but make it a standalone model makes more sense.)

#import "HysteriaPlayer.h"

@interface ViewController : UIViewController <HysteriaPlayerDelegate, HysteriaPlayerDataSource>

There are 4 optional delegates in HysteriaPlayerDelegate:

- (void)hysteriaPlayerWillChangedAtIndex:(NSUInteger)index;
- (void)hysteriaPlayerCurrentItemChanged:(AVPlayerItem *)item;
- (void)hysteriaPlayerRateChanged:(BOOL)isPlaying;
- (void)hysteriaPlayerDidReachEnd;
- (void)hysteriaPlayerCurrentItemPreloaded:(CMTime)time;
- (void)hysteriaPlayerDidFailed:(HysteriaPlayerFailed)identifier error:(NSError *)error;
- (void)hysteriaPlayerReadyToPlay:(HysteriaPlayerReadyToPlay)identifier;

3 optional delegates in HysteriaPlayerDataSource:

- (NSUInteger)hysteriaPlayerNumberOfItems;
- (NSURL *)hysteriaPlayerURLForItemAtIndex:(NSUInteger)index preBuffer:(BOOL)preBuffer;
- (void)hysteriaPlayerAsyncSetUrlForItemAtIndex:(NSUInteger)index preBuffer:(BOOL)preBuffer;

If you don’t implement hysteriaPlayerNumberOfItems delegate method, you have to set itemsCount property to HysteriaPlayer.

And you must implement one of hysteriaPlayerURLForItemAtIndex:preBuffer or hysteriaPlayerAsyncSetUrlForItemAtIndex:preBuffer delegate method.



- (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]];


Get item’s index of my working items:

HysteriaPlayer *hysteriaPlayer = [HysteriaPlayer sharedInstance];
NSNumber *order = [hysteriaPlayer getHysteriaOrder:[hysteriaPlayer getCurrentItem]];

Get playing item’s timescale

HysteriaPlayer *hysteriaPlayer = [HysteriaPlayer sharedInstance];
NSDictionary *dict = [hysteriaPlayer getPlayerTime];
double durationTime = [[dict objectForKey:@"DurationTime"] doubleValue];
double currentTime = [[dict objectForKey:@"CurrentTime"] doubleValue];

Get Player status

switch ([hysteriaPlayer getHysteriaPlayerStatus]) {
    case HysteriaPlayerStatusUnknown:

    case HysteriaPlayerStatusForcePause:

    case HysteriaPlayerStatusBuffering:

    case HysteriaPlayerStatusPlaying:


Disable played item caching

Default is cache enabled

HysteriaPlayer *hysteriaPlayer = [HysteriaPlayer sharedInstance];
[hysteriaPlayer enableMemoryCached:NO];

What if I don’t need player instance anymore?

HysteriaPlayer *hysteriaPlayer = [HysteriaPlayer sharedInstance];
[hysteriaPlayer deprecatePlayer];
hysteriaPlayer = nil;

Known Issues

If you going to play HTTP Live streaming on iOS 8 and below. (iOS 9+ is fine, no worries)
There’s a property you had to set at very first time when HysteriaPlayer is initiated.

HysteriaPlayer *hysteriaPlayer = [HysteriaPlayer sharedInstance];
hysteriaPlayer.skipEmptySoundPlaying = YES;


All source code is licensed under the MIT License.


Created by Saiday

Latest podspec

    "name": "HysteriaPlayer",
    "version": "2.2.2",
    "summary": "Objective-C remote audio player (AVPlayer extends), iOS, OS X compatible",
    "homepage": "",
    "license": "MIT",
    "authors": {
        "Stan Tsai": "[email protected]"
    "source": {
        "git": "",
        "tag": "2.2.2"
    "platforms": {
        "ios": "6.0",
        "osx": "10.9"
    "source_files": "HysteriaPlayer/**/*.{h,m}",
    "resources": "HysteriaPlayer/point1sec.{mp3}",
    "frameworks": [
    "requires_arc": true

Pin It on Pinterest

Share This