Introduction

FreeStreamer is an audio player engine for iOS and OS X, designed for playing audio streams. The engine has a minimal UI for demonstration. Respectfully, see the FreeStreamerDesktop directory for OS X, and,FreeStreamerMobile for the iOS UI.

FreeStreamer 是一个为 iOS 和 OS X 编写的音频播放引擎，用来播放音频流的。这个引擎有一个极简单的 UI 用来示范。你直接查看为 OS X 编写的 FreeStreamerDesktop ，以及为 iOS 编写的 FreeStreamerMobile 。

The engine is written in C++ and the FSAudioController Objective-C class wraps the implementation.

这是用 C++ 写的引擎，用 FSAudioController 类来封装了实现。

FreeStreamer has the following features:

FreeStreamer 有着如下的一些特性：

Fast and low memory footprint (no overhead of Objective-C method calls)
Supports ShoutCast and IceCast audio streams + standard HTTP
Can detect the stream type based on the content type
Supports ShoutCast metadata
Supports interruptions (for example a phone call during playing the stream)
Supports backgrounding
Supports a subset of the ID3v2 tag specification
Supports Podcast RSS feeds
The stream contents can be stored in a file (see the OS X application for an example)
It is possible to access the PCM audio samples (useful if you want your own audio analyzer, for instance)
Includes a frequency analyzer and visualization, see Additions and the iOS application
快速低耗的打印信息（不是 OC 上层方法的调用）
支持 ShoutCast 和 IceCast 音频流 + 标准 HTTP
能检测流类型，基于包的内容
支持 ShoutCast 元数据
支持中断（例如，播放音频流的时候打进来了一个电话）
支持后台
支持 ID3v2 标签子集说明
支持广播 RSS feed
流内容可以保存到文件中（看看 OS X 应用的例子）
他可以处理 PCM 音频
包含一个频率分析器并可视化，可以参考 Additions 的例子

API documentation

See here.

Using the player in your own project

Please follow the following steps to use the player in your own project:

请按照以下的步骤来把它添加到你的工程当中：

Make sure you have the following frameworks linked to your project:（包含如下的框架）
- CFNetwork.framework
- AudioToolbox.framework
- AVFoundation.framework
- libxml2.dylib (add $(SDKROOT)/usr/include/libxml2 to the header search path, if not found)
- MediaPlayer.framework (iOS only)
Add the Common and astreamer directories to your project. Try building the project now and it should compile successfully.（把文件夹 Common 和 astreamer）添加到你的工程当中，试着编译一下看会不会出错。
iOS only: If you want to support background audio, add App plays audio to the target's Required background modes. You can find the property by clicking on the target on Xcode and opening the Info tab.仅支持 iOS ：如果你想支持后台音乐，你可以在 Xcode 的 info tab 中找到相关信息。

You can now stream an audio file like this. Declare the stream in your header file:

你可以这么使用，在你的头文件中声明一下：

@class FSAudioStream;

@interface MyClass : NSObject {
    FSAudioStream *_audioStream;
}

Initialize and use the stream in your implementation:

在你的实现文件中初始化：

#import "FSAudioStream.h"

_audioStream = [[FSAudioStream alloc] init];
[_audioStream playFromURL:[NSURL URLWithString:@"http://www.example.com/audio_file.mp3"]];

Note that FSAudioStream must exist during the playback of the stream. Do not declare the class as a local variable of a method or the stream will be deallocated and will not play.

注意，FSAudioStream 必须在播放音频的期间一直存在。不要把它定义成一个实例变量，一个 alloc init 只能播放一个流媒体。

Some servers may send an incorrect MIME type. In this case, FreeStreamer may not be able to play the stream. If you want to avoid the content-type checks (that the stream actually is an audio file), you can set the following property:

许多服务器也许会给你发送错误的 MIME 类型。这种情况下，FreeStreamer 也许就不能播放这个音频了。如果你想避免 content-type 检查（但是这个 steam 依然是音频文件），你可以设置如下的属性：

audioStream.strictContentTypeChecking = NO;
// Optionally, set the content-type where to fallback to
audioStream.defaultContentType = "audio/mpeg";

For streaming playlists, you need to use the FSAudioController.h class. The class has some additional logic to resolve the playback URLs. Again, declare the class:

为了设置播放列表，你可以使用 FSAudioController.h 类。这个类有着一些额外的逻辑来解决回放问题，声明使用与上面的类似：

@class FSAudioController;

@interface MyClass : NSObject {
    FSAudioController *_audioController;
}

And use it:

这么使用：

#import "FSAudioStream.h"

_audioController = [[FSAudioController alloc] init];
_audioController.url = @"http://www.example.com/my_playlist.pls";
[_audioController play];

It is also possible to check the exact content of the stream by using the FSCheckContentTypeRequest.h andFSParsePlaylistRequest.h classes:

你也可以精确的检查包的内容，使用 FSCheckContentTypeRequest.h 和 FSParsePlaylistRequest.h 这两个类：

FSCheckContentTypeRequest *request = [[FSCheckContentTypeRequest alloc] init];
request.url = @"http://www.example.com/not-sure-about-the-type-of-this-file";
request.onCompletion = ^() {
    if (self.request.playlist) {
        // The URL is a playlist; now do something with it...
    }
};
request.onFailure = ^() {   
};

[request start];

That's it! For more examples, please take a look at the example project. For instance, you may want to observe notifications on the audio stream state.

就这些了！更多例子，请参考示例工程。例如，你也许需要监测视频流的状态。

FAQ

See here.

Debugging

To enable debug logging, enable the following line in astreamer/audio_stream.cpp:

#define AS_DEBUG 1

After enabling the line, compile the code and run it.

It is also possible to check the lastError property in the FSAudioStream class:

NSLog(@"Last error code: %i", audioStream.lastError);

Or if you are using the FSAudioController class, then:

NSLog(@"Last error code: %i", audioController.stream.lastError);

Reporting bugs and contributing

For code contributions, please create a pull request in Github.

For bugs, please create a Github issue. I don't have time for private email support, so usually the best way to get help is to interact in Github.