[翻译] SoundManager 音频管理器

SoundManager 音频管理器

https://github.com/nicklockwood/SoundManager

Purpose

SoundManager is a simple class for playing sound and music in iOS or Mac apps.

SoundManager是一个简单的用来播放音乐的类.

Supported OS & SDK Versions

• Supported build target - iOS 7.0 / Mac OS 10.8 (Xcode 5.0, Apple LLVM compiler 5.0)
• Earliest supported deployment target - iOS 5.0 / Mac OS 10.7
• Earliest compatible deployment target - iOS 4.3 / Mac OS 10.6 (64 bit)
• 支持iOS7.0/Mac OS 10.8
• 支持早期的iOS5.0/Mac OS 10.7
• 兼容早期的iOS4.3

NOTE: 'Supported' means that the library has been tested with this version. 'Compatible' means that the library should work on this iOS version (i.e. it doesn't rely on any unavailable SDK features) but is no longer being tested for compatibility and may require tweaking or bug fixes to run correctly.

注意:支持意味着测试过,兼容意味着可能有bug并且不在维护.

ARC Compatibility

As of version 1.4, SoundManager requires ARC. If you wish to use SoundManager in a non-ARC project, just add the -fobjc-arc compiler flag to the SoundManager.m class. To do this, go to the Build Phases tab in your target settings, open the Compile Sources group, double-click iRate.m in the list and type -fobjc-arc into the popover.

If you wish to convert your whole project to ARC, comment out the #error line in SoundManager.m, then run the Edit > Refactor > Convert to Objective-C ARC... tool in Xcode and make sure all files that you wish to use ARC for (including SoundManager.m) are checked.

1.4版本后就需要ARC了,如果你想把SoundManger用于非ARC工程,加-fobjc-arc编译标签即可.

Installation

To use the SoundManager class in an app, just drag the class files into your project. For iOS apps, or Mac OS apps with a deployment target of 10.7 (Lion) or above you will also need to add the AVFoundation framework.

将class文件夹拖到你的工程中就能够使用了.

Classes

The SoundManager package defines two classes, the SoundManager class itself, which is documented below, and the Sound class, which is used as a wrapper around each sound file being played. The Sound class can be used either directly or with the SoundManager class.

SoundManger封装了2个类,一个SoundManger类以及Sound类,Sound类的每一个实例对象代表一首音乐.Sound类可以单独使用,也可以与SoundManager类配合使用.

Sound properties

@property (nonatomic, readonly, copy) NSString *name;

The name of the sound. This is either the name that was passed to the soundNamed: constructor method, or the last path component of the sound file.

音乐的名字.这既可以表示通过构造方法soundNamed:获取到的名字,也可以表示音乐文件路径中的最后一个元素的名字.

@property (nonatomic, readonly, strong) NSURL *URL;

The absolute URL of the sound file.

音乐文件的绝对URL地址.

@property (nonatomic, readonly) NSTimeInterval duration;

The duration (in seconds) of the sound file.

音乐文件的总持续时间.

@property (nonatomic, assign) NSTimeInterval currentTime;

The current time offset (in seconds) of the sound file. This value is readwrite, so you can (for example) set it to zero to rewind the sound.

当前音乐文件的时间偏移量.这个值是可读可写的,所以,你可以把它设置成0(我打个比方)后来重放.

@property (nonatomic, readonly, getter = isPlaying) BOOL playing;

Returns YES if the sound is currently playing and NO if it isn't (read only).

如果这首歌在播放,则返回YES,否则返回NO(只读).

@property (nonatomic, assign, getter = isLooping) BOOL looping;

Returns YES if the sound has been set to loop, and NO if it hasn't.

如果这首歌被设置成循环播放,则返回YES,否则返回NO.

@property (nonatomic, copy) SoundCompletionHandler completionHandler;

A callback block that will be called when the sound finishes playing, or is stopped. Only one completionHandler block can be set on any given Sound instance, but if you need multiple objects to track the Sound's status, you can add observers for the SoundDidFinishPlayingNotification notification instead.

一个回调的block,当一首音乐播放结束或者暂停的时候就会执行.对于有着多个音乐实例的时候,你只能设定一个回调block.但如果你需要多次观察音乐的状态,你可以注册通知来代替.

@property (nonatomic, assign) float baseVolume;

The maximum volume of the sound. Some sounds are louder than others and it can be annoying trying to manage the volumes of different sounds in your app individually in code. The baseVolume property allows you to equalise the volumes of different sounds on creation, then you can adjust their volumes consistently from that point on.

音乐的最大音量.某些音乐的音量比其他音乐的大,你用代码来管理会很麻烦.这个属性允许你一开始的时候就给音乐的音量初始化了一个值,而之后的调节都是基于这个值来调整的.

@property (nonatomic, assign) float volume;

The sound volume. This is multiplied by the baseVolume property to get the actual volume. Defaults to 1.0 (maximum).

音乐的音量,这个与baseVolume属性相乘以后得到真实的音量,默认值是1.0.

@property (nonatomic, assign) float pan;

The left/right stereo pan of the file. Value ranges from -1.0 to 1.0 and can be used to shift the location of the sound in space. Has no effect on Mac OS 10.6.

文件的左右声道.pan取值范围为-1.0到1.0,用来设置立体声的.

Sound methods

+ (Sound *)soundNamed:(NSString *)name;

This is a handy shorthand constructor method that returns a sound based on the name of a file in the application bundle. If the file extension is omitted, it is assumed to be a .caf file. If you pass a fully-qualified path to this method then it behaves the same way as soundWithContentsOfFile:.

这是一个便利构造器方法,用来返回一个在bundle中音乐文件.如果省略了后缀名,那他添加的默认后缀是.caf.如果你传了一个完整的路径,那它就与这个方法soundWithContentsOfFile:是一样的.

+ (Sound *)soundWithContentsOfFile:(NSString *)path;
- (Sound *)initWithContentsOfFile:(NSString *)path;
+ (Sound *)soundWithContentsOfURL:(NSURL *)URL;
- (Sound *)initWithContentsOfURL:(NSURL *)URL;

These methods create a new Sound instance from a file path or URL.

这些方法用来从一个文件路径或者URL地址来创建音乐实例.

- (void)fadeTo:(float)volume duration:(NSTimeInterval)duration;

This method fades a sound from it's current volume to the specified volume over the specified time period. Note that this method will not play the sound, so you will need to call play prior to calling this method, unless the sound is already playing.

这个方法用来让你从当前音量到你指定的音量之间的一种过渡效果.注意,这个方法不会播放音乐,你需要正在播放音乐的时候使用这个方法.

- (void)fadeIn:(NSTimeInterval)duration;

Fades the sound volume from 0.0 to 1.0 over the specified duration. The sound volume will be set to zero if it not already. See the caveat above about sounds that aren't playing.

将音量从0过渡到最大的音量.如果音乐还没准备好,音量会被设置成0.

- (void)fadeOut:(NSTimeInterval)duration;

Fades the sound from it's current volume to 0.0 over the specified duration. When the sound volume reaches zero, the sound's stop method is automatically called.

将当前音量过渡到0,通过你指定的时间.当音量到0的时候,音乐停止的方法会自动执行.

- (void)play;

Plays the sound. Has no effect if the sound is already playing.

播放音乐,如果音乐正在播放,如果执行此方法将没有效果.

- (void)stop;

Stops the sound. Has no effect if the sound is not already playing. Stopping the sound does not reset the currentTime, so playing a stopeed sound will resume from the last played time.

暂停音乐,如果这个音乐没有播放,执行此方法没有效果.暂停这个音乐不会重设当前时间,所以,你可以使用resume方法来继续播放暂停的音乐.

SoundManager properties

@property (nonatomic, readonly, getter = isPlayingMusic) BOOL playingMusic;

This readonly property reports if the SoundManager is currently playing music.

只读属性,用来报告当前的SoundManager是否正在播放音乐.

@property (nonatomic, assign) BOOL allowsBackgroundMusic;

This property is used to control the audio session on the iPhone to allow iPod music to be played in the background. It defaults to NO, so it should be set to YES before you attempt to play any sound or music if you do not want the iPod music to be interrupted. It does nothing on Mac OS currently.

这个属性用来控制音频会话的,能允许iPod音乐在后台播放,默认值为NO.

@property (nonatomic, assign) float soundVolume;

Sets the sound volume. Affects all currently playing sounds as well as any sounds played subsequently. Should be in the range 0 - 1.

设置音乐音量,影响当前正在播放的音乐,同时也影响添加进队列待播放的音乐.取值范围为0-1.

@property (nonatomic, assign) float musicVolume;

Sets the music volume. Affects currently playing music track as well as any music tracks played subsequently. Should be in the range 0 - 1.

设置音乐音量.影响当前正在播放的音乐同时也也影响播放队列中的音乐.取值范围为0-1.

@property (nonatomic, assign) NSTimeInterval musicFadeDuration;

The fade in/out and crossfade duration for music tracks (defaults to 1 second).

两个音乐渐入渐出交叉的效果,默认1s.

@property (nonatomic, assign) NSTimeInterval soundFadeDuration;

The fade out time for sounds when stopSound is called (defaults to 1 second).

渐变消失效果,当stopSound被调用的时候,默认1s.

SoundManager methods

+ (SoundManager *)sharedManager;

This class method returns a shared singleton instance of the SoundManager.

返回SoundManger的单例.

- (void)prepareToPlay;

The prepareToPlay method preloads a random sound from your application bundle, which initialises the audio playback. It should be called before you attempt to play any audio, ideally during the startup sequence, to eliminate the delay when you first play a sound or music track. Note: this will only work if at least one sound file is included in the root of your application bundle. If all of your sound files are in folders, consider adding an additional short, silent sound file for initialisation purposes, or use the prepareToPlayWithSound: method instead.

prepareToPlay方法预加载了bundle中的音乐,你需要在播放任何音频之前先调用它.尤其是开始播放队列音乐的时候.为了消除延迟,你需要开始时播放一首音乐.注意:你至少得添加一首音乐才能播放.如果所有你的音乐都在文件夹中,你可以考虑添加一个额外的,静音的音乐来达到初始化的目的,要不你就使用这个方法prepareToPlayWithSound:来代替.

- (void)prepareToPlayWithSound:(id)soundOrName;

If your sounds are not located in the root of the application bundle (or even in the bundles at all) then the standard prepareToPlay method won't work. In this case you can use the prepareToPlayWithSound: method instead and specify a particular sound to use for initialisation. The parameter can be a filename, path (either relative or absolute) or an instance of the Sound class.

如果你的音乐不在bundle中,那标准的prepareToPlay方法无效.这种情形下,你需要使用prepareToPlayWithSound:方法代替,使用一个指定的方法来初始化.参数可以使一个文件名,文件路径(绝对或者相对),或者是一个Sound对象的实例.

- (void)playSound:(id)soundOrName looping:(BOOL)looping fadeIn:(BOOL)fadeIn;
- (void)playSound:(id)soundOrName looping:(BOOL)looping;
- (void)playSound:(id)soundOrName;

The play method will play a sound. The parameter can be either a previously created Sound instance, or a name or path for a sound file to be loaded. You can include the file extension in the name, or omit it, in which case the SoundManager will look for a matching file with the .caf file extension. If the looping argument is YES, the sound will continue to play until stopSound: is called. If the fadeIn argument is YES, the sound will fade in from zero to full volume over the time specified by the soundFadeDuration property of the SoundManager class. If omitted, looping and fadeIn both default to NO.

播放的方法,将要播放音乐.参数可以使一个创建的Sound实例,或者一个名字,或者文件路径.你可以在文件名中包含扩展名,或者不要也行.如果looping参数为YES,这个音乐会一直播放,知道stopSound:被调用了.如果fadeIn参数为YES,音乐文件就会渐变出现声音.

- (void)stopSound:(id)soundOrName fadeOut:(BOOL)fadeOut;
- (void)stopSound:(id)soundOrName;

This method will either stop the sound immediately, or fade it out over the period specified bysoundFadeDuration, depending on the fadeOut argument (defaults to YES). The soundOrName parameter can be either a previously created Sound instance, or a name or path. If there are multiple instances of the sound playing then they will all be stopped.

这个方法会立即的停止播放的音乐,或者渐变的停止播放的音乐.依赖于这个参数fadeOut的设置.

- (void)stopAllSounds:(BOOL)fadeOut;
- (void)stopAllSounds;

This method will stop and/or fade out all currently-playing sounds, but not music. It is equivalent to callingstopSound for each sound that is playing.

这个方法会停止/渐变停止当前所有播放的声音,但不是音乐.它与每首音乐自己调用callingstopSound方法一样的效果.

- (void)playMusic:(id)soundOrName looping:(BOOL)looping fadeIn:(BOOL)fadeIn;
- (void)playMusic:(id)soundOrName looping:(BOOL)looping;
- (void)playMusic:(id)soundOrName;

This method plays a music track. If the fadeIn argument is YES, the music will fade in from silent to the volume specified by the musicVolume property over a period of time specified by musicFadeDuration (defaults to YES if omitted). The sound manager only allows one music track to be played at a time, so if an existing track is playing it will be faded out. If the looping argument is YES, the music will continue to play until stopMusic is called (defaults to YES if omitted).

这个方法是用来播放音乐的.如果fadeIn尝试为YES,则音乐会渐变出声音.这个sound manager一次只能让一个音轨播放,如果存在其他播放的音乐,其他的音乐就会渐变的消音后来播放当前音乐,如果looping参数被设置成了YES,那只有调用了stopMusic方法才能够停止被播放的音乐.

- (void)stopMusic:(BOOL)fadeOut;
- (void)stopMusic;

This will stop and/or fade out the currently playing music track over the period specified by musicFadeDuration.

这个方法会渐变的停止当前播放的音乐.

Notifications

SoundDidFinishPlayingNotification

This notification is fired (via NSNotificationCenter) whenever a sound finishes playing, either due to it ending naturally, or because the stop method was called. The notification object is an instance of the Sound class, which is used internally by SoundManager to play sound and music files. You can access the Sound class'sname property to find out which sound has finished.

你可以通过通知中心来监听播放状态,可以监听他是自然的播放结束了还是一个暂停的方法被执行而结束了.这个传递的通知对象是一个Sound实例-----SoundManger专门用来播放音乐的类.你可以查看Sound类中的属性名字来查看哪首音乐播放结束了.

Supported Formats

The iPhone can be quite picky about which sounds it will play. For best results, use .caf files, which you can generate using the afconvert command line tool. Here are some common configurations:

iPhone十分挑剔它要播放的音乐文件,为了达到最好的效果,请使用.caf文件.你可以通过下面的命令行来转化.

For background music (mono):

/usr/bin/afconvert -f caff -d aac -c 1 {input_file_name} {output_file_name}.caf

For background music (stereo):

/usr/bin/afconvert -f caff -d aac {input_file_name} {output_file_name}.caf

For sound effects (mono):

/usr/bin/afconvert -f caff -d ima4 -c 1 {input_file_name} {output_file_name}.caf

For sound effects (stereo):

/usr/bin/afconvert -f caff -d ima4 {input_file_name} {output_file_name}.caf

Release Notes

Version 1.4.1

• SoundCompletionHandler block no longer returns NO for didFinish when sound finished playing correctly
• Now conforms to -Wextra warning level

Version 1.4

• Added duration and currentTime properties
• Added pan property
• Fixed crash due to modifying array during enumeration
• stopMusic method now respects the fadeOut property
• Now requires ARC
• Now requires a 64 bit processor on Mac OS
• Now conforms to -Wall and -Wextra warning levels
• Added podspec

Version 1.3.1

• For Mac OS projects with a deployment target of Mac OS 10.7 (Lion) or above, SoundManager now uses AVAudioPlayer instead of NSSound

Version 1.3

• Added block-based completion handler callback for Sound class
• Sound manager can now play sounds either by name or by object reference
• Extended SoundManager class with additional fading options
• Can now preload sounds that are not in the root application bundle

Version 1.2.1

• The prepareToPlay method no longer crashes if the project includes no sound files

Version 1.2

• Added automatic support for ARC compile targets
• Now requires Apple LLVM 3.0 compiler target
• playing, looping and playingMusic properties now use more standard getter names
• Sound class initialisers refactored to match iOS conventions
• Sound name method now returns name including file extension

Version 1.1.3

• Fixed bug where preloading only worked with .caf files.
• Renamed FILE_EXTENSION to DEFAULT_FILE_EXTENSION to avoid confusion.

Version 1.1.2

• Fixed occasional crash due to accessing sound after it is released
• Sound manager will now log a warning to the console when passed a non-existent sound file instead of crashing
• Sound names can now include directory separators. This means that sounds in subfolders of the resource folder can be played using the standard play functions.

Version 1.1.1

• Fixed bugs with music fading
• Changed default music fade/crossfade duration to 1 seconds
• Exposed looping property on Sound class
• Changed documentation and licence to markdown format

Version 1.1

• Added looping argument to play methods
• Added stopSound and stopAllSounds methods
• Implemented preloading for Mac OS

Version 1.0

• Initial release

使用示例(请添加如下代码):

#ifndef MUSIC_CENTER
#define  MUSIC_CENTER  [SoundManager sharedManager]
#endif