[翻譯] 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