AS3的Sound类[语法参考]

今天把官方的语法帮助翻译一下,帮助自己学习

Class Sound
Sound类

封装包 flash.media
类        全局Sound类(不知道咋翻译了)
继承    Sound -> EventDispatcher ->Object
子类    SoundAsset

Sound类能使你在程序中使用声音,Sound类能让你创建一个新的声音对象,在这个对象中载入和播放外部的mp3文件(还是只有mp3啊),关闭声音 流,并访问声音信息,如声音流的大小以及ID3信息.有关控制声音的更多细节请参考Soundchannel对象与Microphone对象,这些对象能 通过SoundTransform对象的属性来控制输出到计算机扬声器的音频信号.

要控制swf文件中的声音,使用SoundMixer类中的属性.

提醒:AS3.0的API与2.0不同,在ActionScript3.0中,您无法通过将Sound对象置于层中来控制它们的属性.

当您使用这个类时,请注意Flash Player安全沙箱:

• 
  
• 如果swf文件处在网络沙箱内,而欲加载的声音文件是本地的,那么加载与播放将不允许
• 默认条件下,本地的swf文件不允许加载或播放网络中的声音.用户必须通过授权来准许访问
• 上述对声音的操作将受到限制.当前域中swf文件将无权读取其他域中的声音数据,但您可以制定一个跨域规则在受限区域中无效的与 sound相关的API有Sound.id3,SoundMixer.computeSpectrum(), SoundMixer.bufferTime和SoundTransform对象

公用属性:
bytesLoaded:uint(16位无符号整数)
[只读]返回当前声音对象的可用字节数

bytesTotal:int
[只读]返回声音对象的总字节数

id3:id3信息
[只读]为读取mp3文件中的metadata提供访问方法

isBuffering:布尔
[只读]返回外部mp3文件的缓冲状态

length:number(数值)
[只读]以微秒表示的当前声音长度

url:String(字符串)
[只读]读取的声音来源

公用方法:
Sound(stream:URLRequest = null, context:SoundLoaderContext = null)
创建一个新的Sound对象.

close():void
关闭音频流,会导致所有的下载数据的丢弃.

load(stream:URLRequest, context:SoundLoaderContext = null):void
初始化外部mp3文件的加载.

play(startTime:Number = 0, loops:int = 0, sndTransform:SoundTransform = null):SoundChannel
生成一个新的SoundChannel对象来进行回放.

Events事件:
complete 当数据成功加载时被发送.
id3          当MP3声音的ID3数据可用时被发送.
ioError    当输入输出错误导致加载失败时被发送.
open       当加载操作开始时被发送.
progress 当加载操作正在进行且受到数据时被发送.

属性细节:
bytesLoaded 属性

bytesLoaded:uint   [只读]
返回当前声音对象的可用字节数.常常只用于外部加载.

Implementation (实现)
public function get bytesLoaded():uint


bytesTotal 属性

bytesTotal:int   [只读]
返回当前声音对象的总字节数.

Implementation (实现)
public function get bytesTotal():int

id3 属性

id3:ID3Info   [只读]
提供访问mp3文件元数据的方法.

Mp3声音文件可包含ID3标签,ID3标签提供文件的元数据.如果一个你使用Sound.load()方法加载的mp3文件包含了ID3标签,你可以查询这些属性.只有使用UTF-8编码的ID3标签能够被支持.
Flash Player 9以及后续版本支持ID3 2.0标签,特别是2.3和2.4.下面的表格列出了标准的ID3 2.0标签与表示标签内容的格式.Sound.id3属性提供了读取这些标签的格式,如 my_sound.id3.COMM,my_sound.id3.TIME等等.第一个表中描述的标签能够通过ID3 2.0的属性名和动作脚本的属性名来访问.第二张表中描述的ID3标签虽然被支持但在动作脚本中没有预先定义

ID3 2.0标签                      对应的ActionScript属性
COMM                               Sound.id3.comment
TALB                               Sound.id3.album
TCON                               Sound.id3.genre
TIT2                               Sound.id3.songName
TPE1                               Sound.id3.artist
TRCK                               Sound.id3.track
TYER                               Sound.id3.year


下面的表中描述的ID3标签在动作脚本中没有预先定义.您可以通过下面的方式访问它们,例如mySound.id3.TFLT, mySound.id3.TIME等等.

属性                                      描述
TFLT                               文件类型
TIME                                  时间
TIT1                               包含群组描述
TIT2                               标题/歌曲名/描述
TIT3                               子标题/详细说明
TKEY                                   起始地址
TLAN                                      语言
TLEN                                      长度
TMED                                   媒体类型
TOAL                            原专辑/电影/显示标题
TOFN                               原文件名
TOLY                               作词作曲
TOPE                            艺术家/表演者
TORY                                  发行年
TOWN                         文件所有者/许可
TPE1                               主要表演者/主唱
TPE2                                  乐队/伴奏
TPE3                         Conductor/performer refinement
TPE4                            合声,混音,或其他制作人
TPOS                               Part of a set
TPUB                                  出版发行
TRCK                               音轨号/曲目号
TRDA                                  录制日期
TRSN                               网络发射台名称
TRSO                               网络发射台所有人
TSIZ                                        尺寸
TSRC                               ISRC 国际标准记录编码(international standard recording code)
TSSE                               软/硬编码及设置
TYER                                         年份
WXXX                                  链接页面


又是网络沙箱,这段略过

PS:突然发现蓝色理想有id3v2的信息,比我这好多了
贴在这里

isBuffering 属性

isBuffering:Boolean   [只读]
返回外部mp3文件的缓冲状态.如果值为真,则当对象等待数据时回放将会挂起.

Implementation(实现)
public function get isBuffering():Boolean


length 属性

length:Number   [只读]
以微秒表示的当前声音长度.

Implementation 实现
public function get length():Number


url 属性

url:String   [只读]
所加载的声音的地址.该属性只对用Sound.load()方式加载的Sound对象有效.对于关联到swf库中声音资源的Sound对象url属性的返回值为null.

当你第一次调用Sound.load()函数,url属性将会赋值为null,因为最终的url还不确定.当Sound对象中传出open事件的同时,url属性会立即变为非空值.

url属性包含了加载的声音的最终的绝对的地址.通常情况下,url的值与传给Sound.load()的参数值一致.不过,如果你将相对的地址作为参数 传给Sound.load(),那么url属性值将会返回出绝对的地址. 另外,如果原来的地址请求被http服务器重定向,那么url属性值反映的是声音文件所在的真实地址.这个最终绝对的地址的报告与等价于 LoaderInfo.url的行为.

Implementation 实现
public function get url():String

构造函数 详细
Sound () 函数

public function Sound(stream:URLRequest = null, context:SoundLoaderContext = null)
创建一个新的Sound对象.如果你将一个有效的URLRequest对象传递给Sound函数,函数将自动调用Sound对象的load()函数.如果 你没有将有效的URLRequest对象传递给Sound构造函数,你必须亲自调用load()函数,否则,音频流将不会被加载.

一旦Sound对象中的load()被调用,您不能再向该Sound对象加载另一个声音文件.若要载入另一个不同的声音文件,请创建一个新的Sound对象.

参数   stream:URLRequest (default = null) — 这个地址指向外部的mp3文件.  
  
相关内容:SoundLoaderContext (default = null) — Minimum number of milliseconds of MP3 data to hold in the Sound object's buffer. The Sound object waits until it has at least this much data before beginning playback and before resuming playback after a network stall. The default value is 1000 (one second).  

方法 细节
close () 方法

public function close():void
关闭音频流,会导致所有的下载数据的终结.调用close()方法之后将不能从音频流中读取数据.


出现   IOError — 流无法被关闭或打开.  

load () 方法

public function load(stream:URLRequest, context:SoundLoaderContext = null):void
初始化从指定地址对外部mp3文件的加载.如果你将一个有效的URLRequest对象传递给Sound函数,函数将自动调用Sound对象的 load()函数.在你没有将有效的URLRequest对象传递给Sound构造函数时,你需要亲自调用load()函数.

一旦Sound对象中的load()被调用,您不能再向该Sound对象加载另一个声音文件.若要载入另一个不同的声音文件,请创建一个新的Sound对象.

沙箱又来了......

参数   stream:URLRequest — A URL that points to an external MP3 file.  
  
有关内容:SoundLoaderContext (default = null) — Minimum number of milliseconds of MP3 data to hold in the Sound object's buffer. The Sound object waits until it has at least this much data before beginning playback and before resuming playback after a network stall. The default value is 1000 (one second).  

发生   IOError — 网络错误导致加载失败.  
  
安全错误SecurityError — 本地的不受信的swf文件无法访问internet.您可以将其重新分类为本地对网络或者将其加入信任列表.  

play () 方法

public function play(startTime:Number = 0, loops:int = 0, sndTransform:SoundTransform = null):SoundChannel
生成一个新的SoundChannel对象来进行回放.此方法返回一个SoundChannel对象,您可以通过这个SoundChannel对象来停止 播放声音和调整音量. (要控制音量,偏移,平衡,通过分配给sound channel的SoundTransform对象来访问.)

参数
   startTime:Number (default = 0) — 用微秒表示的回放开始位置.  
  
loops:int (default = 0) — 定义在sound channel停止回放前声音循环播放的次数.  
  
sndTransform:SoundTransform (default = null) — 分配给声道的SoundTransform对象.  


返回值
   SoundChannel — 一个你用来控制声音的SoundChannel对象.如果你没有声卡或者你已经没有可用的声音通道,这个方法将返回空值null.声音通道的一次性最大可用数是32.

事件细节
complete 事件
事件对象类型:flash.events.Event
Event类属性=flash.events.Event.COMPLETE

当数据成功加载时触发.
完成事件对象的属性值

该事件有如下属性:
属性名称                      属性值
bubbles                                  false
cancelable                             false;默认没有取消
currentTarget                       当前使用监听器检测该事件对象的影片对象
target                               已经完成下载工作的网络对象.target并不总是
                        存在于注册了侦听器的显示列表中.使用currentTarget属性
                        来获取操作当前事件的对象.

参考Sound.load()

id3 事件
事件对象类型:flash.events.Event
Event类 属性值=flash.events.Event.ID3

当mp3声音对象的ID3数据可用时被触发.
该事件有如下属性:
属性名称                      属性值
bubbles                                  false
cancelable                             false;默认没有取消
currentTarget                       当前使用监听器检测该事件对象的影片对象
target                               已经完成下载工作的网络对象.target并不总是
                        存在于注册了侦听器的显示列表中.使用currentTarget属性
                        来获取操作当前事件的对象.

昏...和complete完全一样

参看:Sound.id3

ioError事件
事件对象属性:flash.events.IOErrorEvent
IORrrorEvent类 属性值=flash.events.IOErrorEvent.IO_ERROR
当输入输出错误导致加载操作失败时被触发.

该事件有如下属性:
属性名称                      属性值
bubbles                                  false
cancelable                             false;默认没有取消
currentTarget                       当前使用监听器检测该事件对象的影片对象
target                               发生输入输出错误的网络对象
text                                  作为错误信息输出的文字信息

参看
Sound.load()

open事件
事件对象类型:flash.events.Event
Event类 属性值=flash.events.Event.OPEN

当加载操作开始时被触发.
该事件有如下属性:
属性名称                      属性值
bubbles                                  false
cancelable                             false;默认没有取消
currentTarget                       当前使用监听器检测该事件对象的影片对象
target                                   开始连接的网络对象

又参看
Sound.load()

progress事件
事件对象类型:flash.events.ProgressEvent
ProgressEvent类 属性值=flash.events.ProgressEvent.PROGRESS

当加载操作运作中收到数据时被触发

该事件有如下属性:

属性名称                      属性值
bubbles                                  false
bytesloaded                   侦听器检测到事件时所加载的条目个数或者比特数
bytestotal                      当加载进程成功完成时预计加载的总数或者总比特数
cancelable                             false;默认没有取消
currentTarget                       当前使用监听器检测该事件对象的影片对象
target                               报告正在工作中的网络对象

参看
Sound.load()

例子:
下面的例子将向您展示发生在mp3文件打开与播放时的声音事件及其信息.要运行这个例子,在与您的swf文件相同目录下放置一个名字为"Mysound.mp3"的文件.
package {
import flash.display.Sprite;
import flash.events.*;
import flash.media.Sound;
import flash.media.SoundChannel;
import flash.net.URLRequest;

public class SoundExample extends Sprite {
       private var url:String = "MySound.mp3";
       private var song:SoundChannel;

       public function SoundExample() {
         var request:URLRequest = new URLRequest(url);
         var soundFactory:Sound = 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);
         song = soundFactory.play();
       }

       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);
       }

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

peterd_mm 于2006年七月25日下午8点25分留言:
bytesTotal属性,在总比特数无法确定的情况下返回零值.(比如,下载初始化时,服务器没有传送HTTP头)
The bytesTotal property, returns 0 if the number of total bytes can't be determined (for example, if the download was initiated but the server did not transmit an HTTP content-length).

Peter
Flash Player documentation
Adobe Systems Incorporated

完成!!