StageVideo API 사용

Stage.stageVideos 속성은 StageVideo 인스턴스에 액세스할 수 있도록 하는 Vector 객체입니다. 이 벡터에는 하드웨어 및 시스템 리소스에 따라 StageVideo 객체를 최대 4개까지 포함할 수 있습니다. 휴대 장치의 경우 그 수는 1개 또는 0개로 제한될 수 있습니다.

스테이지 비디오를 사용할 수 없는 경우 이 벡터는 아무 객체도 포함하지 않습니다. 런타임 오류를 방지하려면 최신 StageVideoAvailability 이벤트가 스테이지 비디오를 사용할 수 있다고 알리는 경우에만 이 벡터의 멤버에 액세스하십시오.

StageVideo API 프레임워크에서 제공하는 이벤트는 다음과 같습니다.

StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY

Stage.stageVideos 속성이 변경되면 전송됩니다. StageVideoAvailabilityEvent.availability 속성은 AVAILABLE 또는 UNAVAILABLE 중 하나를 나타냅니다. 이 이벤트를 사용하면 Stage.stageVideos 벡터의 길이를 직접 확인하지 않고도 stageVideos 속성이 StageVideo 객체를 포함하는지 알아낼 수 있습니다.

StageVideoEvent.RENDER_STATE

NetStream 또는 Camera 객체가 StageVideo 객체에 연결되어 재생되고 있는 경우에 전송됩니다. 현재 사용 중인 디코딩 유형(하드웨어, 소프트웨어 또는 사용 불가[아무 것도 표시되지 않음])을 나타냅니다. 이벤트 대상에는 비디오 뷰포트 크기 조정에 사용하기에 적합한 videoWidth 및 videoHeight 속성이 들어 있습니다.

중요: StageVideo 대상 객체로부터 구한 좌표는 표준 표시 목록에 속하지 않기 때문에 스테이지 좌표를 사용합니다.

VideoEvent.RENDER_STATE

Video 객체가 사용되고 있는 경우에 전송되며, 소프트웨어 또는 하드웨어 가속 디코딩 중 어느 쪽을 사용하고 있는지 나타냅니다. 이 이벤트가 하드웨어 가속 디코딩을 나타낼 경우 가능하면 StageVideo 객체로 전환하십시오. Video 이벤트 대상에는 비디오 뷰포트 크기 조정에 사용하기에 적합한 videoWidth 및 videoHeight 속성이 들어 있습니다.

다음 최상위 단계에 따라 StageVideo 기능을 구현합니다.

1. StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY 이벤트를 수신하여 Stage.stageVideos 벡터가 변경된 경우를 확인합니다. StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY 이벤트 사용 을 참조하십시오.

2. StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY 이벤트가 스테이지 비디오를 사용할 수 있다고 보고하면 이벤트 핸들러 내의 Stage.stageVideos Vector 객체를 사용하여 StageVideo 객체에 액세스합니다.

3. StageVideo.attachNetStream() 을 사용하여 NetStream 객체를 연결하거나, StageVideo.attachCamera() 를 사용하여 Camera 객체를 연결합니다.

4. NetStream.play() 를 사용하여 비디오를 재생합니다.

5. StageVideo 객체에서 StageVideoEvent.RENDER_STATE 이벤트를 수신하여 비디오 재생 상태를 확인합니다. 이 이벤트 수신은 비디오의 폭 및 높이 속성이 초기화되었거나 변경되었음을 나타내기도 합니다. StageVideoEvent.RENDER_STATE 및 VideoEvent.RENDER_STATE 이벤트 사용 을 참조하십시오.

6. Video 객체에서 VideoEvent.RENDER_STATE 이벤트를 수신합니다. 이 이벤트는 StageVideoEvent.RENDER_STATE 와 동일한 상태를 제공하므로 GPU 가속의 사용 가능 여부를 결정하는 데도 사용할 수 있습니다. 이 이벤트 수신은 비디오의 폭 및 높이 속성이 초기화되었거나 변경되었음을 나타내기도 합니다. StageVideoEvent.RENDER_STATE 및 VideoEvent.RENDER_STATE 이벤트 사용 을 참조하십시오.

응용 프로그램 초기화를 수행하는 동안 StageVideoAvailabilityEvent 및 VideoEvent 리스너를 설정하십시오. 예를 들어 이 리스너를 flash.events.Event.ADDED_TO_STAGE 이벤트 핸들러에서 초기화할 수 있습니다. 이 이벤트는 응용 프로그램이 스테이지상에서 계속 보이도록 합니다.

public class SimpleStageVideo extends Sprite 
    private var nc:NetConnection; 
    private var ns:NetStream; 
 
    public function SimpleStageVideo() 
    { 
        // Constructor for SimpleStageVideo class 
        // Make sure the app is visible and stage available 
        addEventListener(Event.ADDED_TO_STAGE, onAddedToStage); 
    } 
     
    private function onAddedToStage(event:Event):void 
    { 
        //... 
        // Connections 
        nc = new NetConnection(); 
        nc.connect(null); 
        ns = new NetStream(nc); 
        ns.addEventListener(NetStatusEvent.NET_STATUS, onNetStatus); 
        ns.client = this; 
 
        // Screen 
        video = new Video(); 
        video.smoothing = true; 
 
        // Video Events 
        // the StageVideoEvent.STAGE_VIDEO_STATE informs you whether 
        // StageVideo is available 
        stage.addEventListener(StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY, 
            onStageVideoState); 
        // in case of fallback to Video, listen to the VideoEvent.RENDER_STATE 
        // event to handle resize properly and know about the acceleration mode running 
        video.addEventListener(VideoEvent.RENDER_STATE, videoStateChange); 
        //... 
    }

StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY 핸들러에서 StageVideo의 가용성에 따라 Video 또는 StageVideo 객체 중 어느 것을 사용할지 결정하십시오. StageVideoAvailabilityEvent.availability 속성이 StageVideoAvailability.AVAILABLE 로 설정되어 있으면 StageVideo를 사용합니다. 이 경우에 Stage.stageVideos 벡터를 활용해 하나 이상의 StageVideo 객체를 포함할 수 있습니다. Stage.stageVideos 속성에서 StageVideo 객체를 구하여 여기에 NetStream 객체를 연결합니다. StageVideo 객체는 항상 배경에 나타나므로 기존의 모든 Video 객체(항상 전경에 나타남)를 제거합니다. 또한 이 이벤트 핸들러를 활용하여 StageVideoEvent.RENDER_STATE 이벤트에 대한 리스너를 추가합니다.

StageVideoAvailabilityEvent.availability 속성이 StageVideoAvailability.UNAVAILABLE 로 설정되어 있으면 StageVideo를 사용하지 않거나 Stage.stageVideos 벡터에 액세스하지 않도록 합니다. 이 경우 NetStream 객체를 Video 객체에 연결합니다. 마지막으로 StageVideo 또는 Video 객체를 스테이지에 추가하고 NetStream.play() 를 호출합니다.

다음 코드에서는 StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY 이벤트를 처리하는 방법을 보여 줍니다.

private var sv:StageVideo; 
private var video:Video; 
 
private function onStageVideoState(event:StageVideoAvailabilityEvent):void 
{     
    // Detect if StageVideo is available and decide what to do in toggleStageVideo 
    toggleStageVideo(event.availability == StageVideoAvailability.AVAILABLE); 
} 
 
private function toggleStageVideo(on:Boolean):void 
{     
    // To choose StageVideo attach the NetStream to StageVideo 
    if (on) 
    { 
        stageVideoInUse = true; 
        if ( sv == null ) 
        { 
            sv = stage.stageVideos[0]; 
            sv.addEventListener(StageVideoEvent.RENDER_STATE, stageVideoStateChange); 
                sv.attachNetStream(ns); 
        } 
 
        if (classicVideoInUse) 
        { 
            // If you use StageVideo, remove from the display list the 
            // Video object to avoid covering the StageVideo object 
            // (which is always in the background) 
            stage.removeChild ( video ); 
            classicVideoInUse = false; 
        } 
    } else 
    { 
        // Otherwise attach it to a Video object 
        if (stageVideoInUse) 
            stageVideoInUse = false; 
        classicVideoInUse = true; 
        video.attachNetStream(ns); 
        stage.addChildAt(video, 0); 
    } 
     
    if ( !played ) 
    { 
        played = true; 
        ns.play(FILE_NAME); 
    } 
} 

이 샘플 응용 프로그램의 전체 소스 코드는 스테이지 비디오 시작 에서 다운로드할 수 있습니다.

StageVideo 및 Video 객체는 디스플레이 환경이 변할 때 이를 응용 프로그램에 알려 주는 이벤트를 전송합니다. 이러한 이벤트는 StageVideoEvent.RENDER_STATE 및 VideoEvent.RENDER_STATE 입니다.

StageVideo 또는 Video 객체는 NetStream 객체가 연결되어 재생이 시작되면 렌더링 상태 이벤트를 전달합니다. 또한 디스플레이 환경이 변경될 때(예: 비디오 뷰포트 크기가 조정될 때)도 이 이벤트를 전송합니다. 이러한 알림을 사용하여 뷰포트를 이벤트 대상 객체의 현재 videoHeight 및 videoWidth 값으로 재설정합니다.

보고되는 렌더링 상태는 다음과 같습니다.

• RENDER_STATUS_UNAVAILABLE

• RENDER_STATUS_SOFTWARE

• RENDER_STATUS_ACCELERATED

렌더링 상태는 현재 비디오를 재생하고 있는 클래스에 관계없이 하드웨어 가속 디코딩이 사용 중일 때를 나타냅니다. StageVideoEvent.status 속성에서 필요한 디코딩을 사용할 수 있는지 여부를 확인하십시오. 이 속성이 “unavailable”로 설정되면 StageVideo 객체가 비디오를 재생할 수 없습니다. 이 상태에서는 즉시 NetStream 객체를 Video 객체에 다시 연결해야 합니다. 그 밖의 상태는 응용 프로그램에 현재 렌더링 상태를 알립니다.

다음 표에는 Flash Player의 StageVideoEvent 및 VideoEvent 객체에 대한 모든 렌더링 상태 값의 의미가 나와 있습니다.

스테이지 비디오는 기본 하드웨어 기능을 사용하여 색상 공간을 지원합니다. SWF 내용은 기본 색상 공간을 알려 주는 메타데이터를 제공할 수 있습니다. 그러나 장치 그래픽 하드웨어는 해당 색상 공간을 사용할 수 있는지 여부를 결정합니다. 장치에 따라 여러 색상 공간을 지원할 수도 있고 하나도 지원하지 못할 수도 있습니다. 하드웨어에서 요청된 색상 공간을 지원하지 않는 경우 Flash Player는 지원되는 색상 공간 중에서 가장 근사하게 일치하는 색상 공간을 찾습니다.

하드웨어에서 지원하는 색상 공간을 쿼리하려면 StageVideo.colorSpaces 속성을 사용하십시오. 이 속성은 지원되는 색상 공간의 목록을 String 벡터로 반환합니다.

var colorSpace:Vector.<String> = stageVideo.colorSpaces();

현재 재생 중인 비디오에서 사용되는 색상 공간을 알아보려면 StageVideoEvent.colorSpace 속성을 확인하십시오. 이 속성은 StageVideoEvent.RENDER_STATE 이벤트의 이벤트 핸들러에서 확인할 수 있습니다.

var currColorSpace:String; 
 
//StageVideoEvent.RENDER_STATE event handler 
private function stageVideoRenderState(event:Object):void 
{ 
    //... 
    currColorSpace = (event as StageVideoEvent).colorSpace; 
    //... 
}

Flash Player에서 지원되지 않는 색상 공간의 대체 공간을 찾을 수 없는 경우 스테이지 비디오는 기본 색상 공간인 BT.601을 사용합니다. 예를 들어 H.264 인코딩의 비디오 스트림은 보통 BT.709 색상 공간을 사용합니다. 장치 하드웨어에서 BT.709를 지원하지 않는 경우 colorSpace 속성은 BT601 을 반환합니다. StageVideoEvent.colorSpace 의 unknown 값은 하드웨어에서 색상 공간의 쿼리 방법을 제공하지 않는다는 것을 나타냅니다.

응용 프로그램에서 현재의 색상 공간을 허용할 수 없는 것으로 간주하면 StageVideo 객체에서 Video 객체로 전환하도록 선택할 수 있습니다. Video 클래스는 소프트웨어 합성을 통해 모든 색상 공간을 지원합니다.