MediaSyncEvent.java revision 505e5c8859f596ed58489be565d6e029314b2ac8
1505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent/* 2505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * Copyright (C) 2012 The Android Open Source Project 3505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * 4505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * Licensed under the Apache License, Version 2.0 (the "License"); 5505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * you may not use this file except in compliance with the License. 6505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * You may obtain a copy of the License at 7505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * 8505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * http://www.apache.org/licenses/LICENSE-2.0 9505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * 10505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * Unless required by applicable law or agreed to in writing, software 11505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * distributed under the License is distributed on an "AS IS" BASIS, 12505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * See the License for the specific language governing permissions and 14505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * limitations under the License. 15505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent */ 16505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 17505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurentpackage android.media; 18505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 19505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent/** 20505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * The MediaSyncEvent class defines events that can be used to synchronize playback or capture 21505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * actions between different players and recorders. 22505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * <p>For instance, {@link AudioRecord#startRecording(MediaSyncEvent)} is used to start capture 23505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * only when the playback on a particular audio session is complete. 24505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * The audio session ID is retrieved from a player (e.g {@link MediaPlayer}, {@link AudioTrack} or 25505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * {@link ToneGenerator}) by use of the getAudioSessionId() method. 26505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * @hide 27505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent */ 28505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurentpublic class MediaSyncEvent { 29505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 30505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent /** 31505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * No sync event specified. When used with a synchronized playback or capture method, the 32505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * behavior is equivalent to calling the corresponding non synchronized method. 33505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent */ 34505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent public static final int SYNC_EVENT_NONE = AudioSystem.SYNC_EVENT_NONE; 35505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 36505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent /** 37505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * The corresponding action is triggered only when the presentation is completed 38505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * (meaning the media has been presented to the user) on the specified session. 39505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * A synchronization of this type requires a source audio session ID to be set via 40505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * {@link #setAudioSessionId(int) method. 41505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent */ 42505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent public static final int SYNC_EVENT_PRESENTATION_COMPLETE = 43505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent AudioSystem.SYNC_EVENT_PRESENTATION_COMPLETE; 44505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 45505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 46505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent /** 47505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * Creates a synchronization event of the sepcified type. 48505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * 49505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * <p>The type specifies which kind of event is monitored. 50505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * For instance, event {@link #SYNC_EVENT_PRESENTATION_COMPLETE} corresponds to the audio being 51505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * presented to the user on a particular audio session. 52505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * @param type the synchronization event type. 53505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * @return the MediaSyncEvent created. 54505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * @throws java.lang.IllegalArgumentException 55505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent */ 56505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent public static MediaSyncEvent createEvent(int eventType) 57505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent throws IllegalArgumentException { 58505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent if (!isValidType(eventType)) { 59505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent throw (new IllegalArgumentException(eventType 60505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent + "is not a valid MediaSyncEvent type.")); 61505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } else { 62505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent return new MediaSyncEvent(eventType); 63505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } 64505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } 65505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 66505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent private final int mType; 67505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent private int mAudioSession = 0; 68505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 69505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent private MediaSyncEvent(int eventType) { 70505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent mType = eventType; 71505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } 72505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 73505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent /** 74505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * Sets the event source audio session ID. 75505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * 76505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * <p>The audio session ID specifies on which audio session the synchronization event should be 77505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * monitored. 78505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * It is mandatory for certain event types (e.g. {@link #SYNC_EVENT_PRESENTATION_COMPLETE}). 79505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * For instance, the audio session ID can be retrieved via 80505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * {@link MediaPlayer#getAudioSessionId()} when monitoring an event on a particular MediaPlayer. 81505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * @param audioSessionId the audio session ID of the event source being monitored. 82505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * @return the MediaSyncEvent the method is called on. 83505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * @throws java.lang.IllegalArgumentException 84505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent */ 85505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent public MediaSyncEvent setAudioSessionId(int audioSessionId) 86505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent throws IllegalArgumentException { 87505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent if (audioSessionId > 0) { 88505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent mAudioSession = audioSessionId; 89505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } else { 90505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent throw (new IllegalArgumentException(audioSessionId + " is not a valid session ID.")); 91505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } 92505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent return this; 93505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } 94505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 95505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent /** 96505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * Gets the synchronization event type. 97505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * 98505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * @return the synchronization event type. 99505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent */ 100505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent public int getType() { 101505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent return mType; 102505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } 103505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 104505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent /** 105505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * Gets the synchronization event audio session ID. 106505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * 107505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * @return the synchronization audio session ID. The returned audio session ID is 0 if it has 108505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * not been set. 109505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent */ 110505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent public int getAudioSessionId() { 111505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent return mAudioSession; 112505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } 113505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 114505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent private static boolean isValidType(int type) { 115505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent switch (type) { 116505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent case SYNC_EVENT_NONE: 117505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent case SYNC_EVENT_PRESENTATION_COMPLETE: 118505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent return true; 119505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent default: 120505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent return false; 121505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } 122505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } 123505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent} 124