MediaSyncEvent.java revision 505e5c8859f596ed58489be565d6e029314b2ac8
1/* 2 * Copyright (C) 2012 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.media; 18 19/** 20 * The MediaSyncEvent class defines events that can be used to synchronize playback or capture 21 * actions between different players and recorders. 22 * <p>For instance, {@link AudioRecord#startRecording(MediaSyncEvent)} is used to start capture 23 * only when the playback on a particular audio session is complete. 24 * The audio session ID is retrieved from a player (e.g {@link MediaPlayer}, {@link AudioTrack} or 25 * {@link ToneGenerator}) by use of the getAudioSessionId() method. 26 * @hide 27 */ 28public class MediaSyncEvent { 29 30 /** 31 * No sync event specified. When used with a synchronized playback or capture method, the 32 * behavior is equivalent to calling the corresponding non synchronized method. 33 */ 34 public static final int SYNC_EVENT_NONE = AudioSystem.SYNC_EVENT_NONE; 35 36 /** 37 * The corresponding action is triggered only when the presentation is completed 38 * (meaning the media has been presented to the user) on the specified session. 39 * A synchronization of this type requires a source audio session ID to be set via 40 * {@link #setAudioSessionId(int) method. 41 */ 42 public static final int SYNC_EVENT_PRESENTATION_COMPLETE = 43 AudioSystem.SYNC_EVENT_PRESENTATION_COMPLETE; 44 45 46 /** 47 * Creates a synchronization event of the sepcified type. 48 * 49 * <p>The type specifies which kind of event is monitored. 50 * For instance, event {@link #SYNC_EVENT_PRESENTATION_COMPLETE} corresponds to the audio being 51 * presented to the user on a particular audio session. 52 * @param type the synchronization event type. 53 * @return the MediaSyncEvent created. 54 * @throws java.lang.IllegalArgumentException 55 */ 56 public static MediaSyncEvent createEvent(int eventType) 57 throws IllegalArgumentException { 58 if (!isValidType(eventType)) { 59 throw (new IllegalArgumentException(eventType 60 + "is not a valid MediaSyncEvent type.")); 61 } else { 62 return new MediaSyncEvent(eventType); 63 } 64 } 65 66 private final int mType; 67 private int mAudioSession = 0; 68 69 private MediaSyncEvent(int eventType) { 70 mType = eventType; 71 } 72 73 /** 74 * Sets the event source audio session ID. 75 * 76 * <p>The audio session ID specifies on which audio session the synchronization event should be 77 * monitored. 78 * It is mandatory for certain event types (e.g. {@link #SYNC_EVENT_PRESENTATION_COMPLETE}). 79 * For instance, the audio session ID can be retrieved via 80 * {@link MediaPlayer#getAudioSessionId()} when monitoring an event on a particular MediaPlayer. 81 * @param audioSessionId the audio session ID of the event source being monitored. 82 * @return the MediaSyncEvent the method is called on. 83 * @throws java.lang.IllegalArgumentException 84 */ 85 public MediaSyncEvent setAudioSessionId(int audioSessionId) 86 throws IllegalArgumentException { 87 if (audioSessionId > 0) { 88 mAudioSession = audioSessionId; 89 } else { 90 throw (new IllegalArgumentException(audioSessionId + " is not a valid session ID.")); 91 } 92 return this; 93 } 94 95 /** 96 * Gets the synchronization event type. 97 * 98 * @return the synchronization event type. 99 */ 100 public int getType() { 101 return mType; 102 } 103 104 /** 105 * Gets the synchronization event audio session ID. 106 * 107 * @return the synchronization audio session ID. The returned audio session ID is 0 if it has 108 * not been set. 109 */ 110 public int getAudioSessionId() { 111 return mAudioSession; 112 } 113 114 private static boolean isValidType(int type) { 115 switch (type) { 116 case SYNC_EVENT_NONE: 117 case SYNC_EVENT_PRESENTATION_COMPLETE: 118 return true; 119 default: 120 return false; 121 } 122 } 123} 124