SoundChannel - Adobe ActionScript® 3 (AS3 ) API 參考

套件	flash.media
類別	public final class SoundChannel
繼承	SoundChannel EventDispatcher Object

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

SoundChannel 類別會控制應用程式中的聲音。每個聲音會指定一個聲道，而且應用程式可以有多個混合聲道。SoundChannel 類別含有 stop() 方法、監視聲道振幅 (音量) 的屬性，以及將 SoundTransform 物件指定給聲道的屬性。

相關 API 元素

公用屬性

	屬性		定義自
		constructor : Object 類別物件的參照或是特定物件實體的建構函數。	Object
		leftPeak : Number [唯讀] 左聲道的目前振幅 (音量)，從 0 (靜音) 至 1 (最大振幅)。	SoundChannel
		position : Number [唯讀] 當聲音正在播放時，position 屬性會以毫秒指出聲音檔案中目前正在播放的位置。	SoundChannel
		rightPeak : Number [唯讀] 右聲道的目前振幅 (音量)，從 0 (靜音) 至 1 (最大振幅)。	SoundChannel
		soundTransform : flash.media:SoundTransform 指定給聲道的 SoundTransform 物件。	SoundChannel

公用方法

隱藏繼承公用方法

顯示繼承公用方法

	方法		定義自
		addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void 會在 EventDispatcher 物件註冊事件偵聽程式，以便讓偵聽程式收到事件的通知。	EventDispatcher
		dispatchEvent(event:Event):Boolean 會將事件傳送到事件流程。	EventDispatcher
		hasEventListener(type:String):Boolean 會檢查 EventDispatcher 物件是否有對特定的事件類型註冊偵聽程式。	EventDispatcher
		hasOwnProperty(name:String):Boolean 指出物件是否有已定義的指定屬性。	Object
		isPrototypeOf(theClass:Object):Boolean 指出 Object 類別的實體是否位於指定為參數的物件原型鏈中。	Object
		propertyIsEnumerable(name:String):Boolean 指出指定的屬性是否存在，以及是否可列舉。	Object
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void 會從 EventDispatcher 物件移除偵聽程式。	EventDispatcher
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void 為迴圈作業設定動態屬性的可用性。	Object
		stop():void 會停止在聲道中播放的聲音。	SoundChannel
		toLocaleString():String 傳回代表此物件的字串，根據地區特定慣例進行格式化。	Object
		toString():String 會傳回指定之物件的字串形式。	Object
		valueOf():Object 會傳回指定之物件的基本值。	Object
		willTrigger(type:String):Boolean 檢查此 EventDispatcher 物件是否已註冊事件偵聽程式，或者此物件的任何祖系已為特定事件類型註冊事件偵聽程式。	EventDispatcher

事件

按一下以瞭解事件的詳細資訊

隱藏繼承事件

顯示繼承事件

	摘要	定義自
activate	[廣播事件] 當 Flash Player 或 AIR 應用程式取得作業系統焦點並成為作用中時傳送。	EventDispatcher
deactivate	[廣播事件] 當 Flash Player 或 AIR 應用程式失去作業系統焦點並成為非作用中時傳送。	EventDispatcher
soundComplete	在聲音完成播放時傳送。	SoundChannel

屬性詳細資訊

leftPeak

屬性

leftPeak:Number [唯讀]

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

左聲道的目前振幅 (音量)，從 0 (靜音) 至 1 (最大振幅)。

實作
public function get leftPeak():Number

position

屬性

position:Number [唯讀]

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

當聲音正在播放時，position 屬性會以毫秒指出聲音檔案中目前正在播放的位置。當聲音停止或暫停時，position 屬性會指出聲音檔案中最後播放處。

常用的情況是在聲音停止時將 position 屬性的值儲存起來。之後您可以從儲存的位置重新啟動，繼續播放聲音。

如果這個聲音已被循環，position 會在每次循環的開頭被重設為 0。

實作
public function get position():Number

rightPeak

屬性

rightPeak:Number [唯讀]

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

右聲道的目前振幅 (音量)，從 0 (靜音) 至 1 (最大振幅)。

實作
public function get rightPeak():Number

soundTransform

屬性

soundTransform:flash.media:SoundTransform

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

指定給聲道的 SoundTransform 物件。 SoundTransform 物件包含可用來設定音量、左右相位、指定左邊喇叭，以及指定右邊喇叭的屬性。

實作
public function get soundTransform():flash.media:SoundTransform
public function set soundTransform(value:flash.media:SoundTransform):void

相關 API 元素

SoundTransform

方法詳細資訊

stop

()

方法

public function stop():void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會停止在聲道中播放的聲音。

範例 ( 如何使用本範例 )

在下列範例中，使用者可以暫停並重新播放聲音檔。

建構函式中會載入聲音檔案 (這個範例假設該檔案與 SWF 檔在相同目錄中)。使用文字欄位做為按鈕，供使用者播放或暫停聲音。當使用者選取 button 文字欄位時，會叫用 clickHandler() 方法。

在 clickHandler() 方法中，當使用者第一次選取文字欄位時，會設定開始播放該聲音，並將聲音指定給聲道。接著，當使用者選取文字欄位以暫停時，聲音將會停止播放。聲道的 position 屬性會記錄聲音停止時的位置。當使用者選取文字欄位重新開始播放之後，這個屬性可用來從該位置開始繼續播放聲音。每次呼叫 Sound.play() 方法，都會建立新的 SoundChannel 物件，並指定給 channel 變數。必須將 Sound 物件指定給 SoundChannel 物件，才能使用聲道的 stop() 方法暫停聲音。


package {
    import flash.display.Sprite;
    import flash.media.Sound;
    import flash.media.SoundChannel;
    import flash.net.URLLoader;
    import flash.net.URLRequest;
    import flash.text.TextField;
    import flash.events.MouseEvent;
    import flash.text.TextFieldAutoSize;
            
    public class SoundChannel_stopExample extends Sprite {
        private var snd:Sound = new Sound();
        private var channel:SoundChannel = new SoundChannel();
        private var button:TextField = new TextField();

        public function SoundChannel_stopExample() {
            var req:URLRequest = new URLRequest("MySound.mp3");
            snd.load(req);
            
            button.x = 10;
            button.y = 10;
            button.text = "PLAY";
            button.border = true;
            button.background = true;
            button.selectable = false;
            button.autoSize = TextFieldAutoSize.CENTER;

            button.addEventListener(MouseEvent.CLICK, clickHandler);

            this.addChild(button);
        }

        private function clickHandler(e:MouseEvent):void {
            var pausePosition:int = channel.position;

            if(button.text == "PLAY") {
                channel = snd.play(pausePosition);
                button.text = "PAUSE";
            } 
            else {
                channel.stop();
                button.text = "PLAY";
            }
        }
    }
}

事件詳細資訊

soundComplete

事件

事件物件類型: flash.events.Event
屬性 Event.type = flash.events.Event.SOUND_COMPLETE

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

在聲音完成播放時傳送。

Event.SOUND_COMPLETE 常數會定義 soundComplete 事件物件的 type 屬性值。

這個事件具有下列屬性：

屬性	值
`bubbles`	`false`
`cancelable`	`false`；沒有要取消的預設行為指令。
`currentTarget`	正主動使用事件偵聽程式處理 Event 物件的物件。
`target`	聲音已完成播放的 SoundChannel 物件。

範例 ( 如何使用本範例 )

在下列範例中，使用者會從播放清單中選取歌曲，然後選取「播放」來依選取的順序播放歌曲。

建構函式中會定義一個用於存放歌曲清單的文字欄位，和用於選取開始播放的一行 (一般會使用按鈕控制播放，並使用清單方塊做為歌曲清單)。也會定義一個文字格式物件，在選取歌曲之後將歌曲字行的格式變更為斜體。當使用者選取文字欄位時，會叫用 clickHandler() 方法。

在 clickHandler() 方法中，文字欄位物件的 getLineIndexAtPoint() 會傳回使用者在該行選取的位置索引。getLineText() 方法會利用這個行索引取得文字的內容。 if 陳述式會檢查使用者是選取要播放，或是要將歌曲加入播放清單。如果使用者選取要播放，而且已選取歌曲，則會移除按一下滑鼠的事件偵聽程式，並呼叫 playNext() 方法開始播放歌曲。如果使用者選取的是歌名，則會將該行的內容加入 songList 陣列，並將該行的格式設定為斜體。

playNext() 方法會在陣列清單中重複執行，以載入和播放每首歌曲。歌曲也會指定給聲道。當歌曲播放完畢，並傳送 Event.SOUND_COMPLETE 事件後，便會為聲道加入事件偵聽程式以做為回應。接著，soundCompleteHandler() 方法會叫用 playNext() 方法以播放下一首歌曲。這個程序會一再重複，直到列在陣列中的歌曲都播完為止。

package {
    import flash.display.Sprite;
    import flash.media.Sound;
    import flash.media.SoundChannel;
    import flash.text.TextField;
    import flash.text.TextFieldAutoSize;
    import flash.events.MouseEvent;
    import flash.text.TextFormat;
    import flash.net.URLRequest;
    import flash.events.Event;
    import flash.events.IOErrorEvent;

    public class SoundChannel_event_soundCompleteExample extends Sprite {
        private var channel:SoundChannel = new SoundChannel();
        private var songList:Array = new Array();
        private var listTextField:TextField = new TextField();
        private var songFormat:TextFormat = new TextFormat();
        private var arrayIndex:int = 0;
        private var songSelected:Boolean = false;
        
        public function SoundChannel_event_soundCompleteExample() {
            
            listTextField.autoSize = TextFieldAutoSize.LEFT;
            listTextField.border = true
            listTextField.background = true;
            listTextField.text = "Song1.mp3\n" + "Song2.mp3\n" 
                                + "Song3.mp3\n" + "Song4.mp3\n" + "PLAY";
        
            songFormat.italic = true;
 
            listTextField.addEventListener(MouseEvent.CLICK, clickHandler);
                        
            addChild(listTextField);
        }
        
        private function clickHandler(e:MouseEvent):void {
            var index:int = listTextField.getLineIndexAtPoint(e.localX, e.localY);
            var line:String = listTextField.getLineText(index);
            var firstIndex:uint = listTextField.getLineOffset(index);
            var playLine:uint = listTextField.numLines - 1;

                if((index == playLine) && (songSelected == true)) {
                    listTextField.removeEventListener(MouseEvent.CLICK, clickHandler);
                    playNext();       

                } else if (index != playLine) {
                     songList.push(line.substr(0, (line.length - 1)));
                     listTextField.setTextFormat(songFormat, firstIndex, 
                                (firstIndex + listTextField.getLineLength(index)));     
                    songSelected = true;
                 }
        }

        private function playNext():void {
 
             if(arrayIndex < songList.length) {
                var snd:Sound = new Sound();
                snd.load(new URLRequest(songList[arrayIndex]));
                channel = snd.play();
                
                channel.addEventListener(Event.SOUND_COMPLETE, soundCompleteHandler);
                arrayIndex++;
 
            } else {
                songSelected = false;
                    
                while(arrayIndex > 0) {
                    songList.pop();
                    arrayIndex--;
                }
            }
        }    

        private function soundCompleteHandler(e:Event):void {
            playNext();
        }

        private function errorHandler(errorEvent:IOErrorEvent):void {
            trace(errorEvent.text);
        }
    }
}

範例如何使用本範例

SoundChannelExample.as

下列範例會載入 MP3 檔、播放該檔，並顯示在載入及播放 MP3 檔時發生的聲音事件之相關資訊。 Timer 物件會每隔 50 毫秒，提供播放磁頭位置的更新資訊。若要執行此範例，請將名為 MySound.mp3 的檔案與 SWF 檔放置於相同的目錄中。

package {
    import flash.display.Sprite;
    import flash.events.*;
    import flash.media.Sound;
    import flash.media.SoundChannel;
    import flash.net.URLRequest;
    import flash.utils.Timer;

    public class SoundChannelExample extends Sprite {
        private var url:String = "MySound.mp3";
        private var soundFactory:Sound;
        private var channel:SoundChannel;
        private var positionTimer:Timer;

        public function SoundChannelExample() {
            var request:URLRequest = new URLRequest(url);
            soundFactory = new Sound();
            soundFactory.addEventListener(Event.COMPLETE, completeHandler);
            soundFactory.addEventListener(Event.ID3, id3Handler);
            soundFactory.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            soundFactory.addEventListener(ProgressEvent.PROGRESS, progressHandler);
            soundFactory.load(request);

            channel = soundFactory.play();
            channel.addEventListener(Event.SOUND_COMPLETE, soundCompleteHandler);

            positionTimer = new Timer(50);
            positionTimer.addEventListener(TimerEvent.TIMER, positionTimerHandler);
            positionTimer.start();
        }
        

        private function positionTimerHandler(event:TimerEvent):void {
            trace("positionTimerHandler: " + channel.position.toFixed(2));
        }

        private function completeHandler(event:Event):void {
            trace("completeHandler: " + event);
        }

        private function id3Handler(event:Event):void {
            trace("id3Handler: " + event);
        }

        private function ioErrorHandler(event:Event):void {
            trace("ioErrorHandler: " + event);
            positionTimer.stop();       
        }

        private function progressHandler(event:ProgressEvent):void {
            trace("progressHandler: " + event);
        }

        private function soundCompleteHandler(event:Event):void {
            trace("soundCompleteHandler: " + event);
            positionTimer.stop();
        }
    }
}

法律聲明 | 線上隱私權政策

SoundChannel - AS3

類別 x

leftPeak

position

rightPeak

soundTransform

stop

soundComplete