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 */ 27505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurentpublic class MediaSyncEvent { 28505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 29505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent /** 30505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * No sync event specified. When used with a synchronized playback or capture method, the 31505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * behavior is equivalent to calling the corresponding non synchronized method. 32505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent */ 33505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent public static final int SYNC_EVENT_NONE = AudioSystem.SYNC_EVENT_NONE; 34505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 35505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent /** 36505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * The corresponding action is triggered only when the presentation is completed 37505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * (meaning the media has been presented to the user) on the specified session. 38505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * A synchronization of this type requires a source audio session ID to be set via 39505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * {@link #setAudioSessionId(int) method. 40505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent */ 41505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent public static final int SYNC_EVENT_PRESENTATION_COMPLETE = 42505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent AudioSystem.SYNC_EVENT_PRESENTATION_COMPLETE; 43505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 44505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 45505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent /** 46505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * Creates a synchronization event of the sepcified type. 47505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * 48505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * <p>The type specifies which kind of event is monitored. 49505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * For instance, event {@link #SYNC_EVENT_PRESENTATION_COMPLETE} corresponds to the audio being 50505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * presented to the user on a particular audio session. 51ff2577da370f15b8288f547575c28393477d57b1Eric Laurent * @param eventType the synchronization event type. 52505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * @return the MediaSyncEvent created. 53505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * @throws java.lang.IllegalArgumentException 54505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent */ 55505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent public static MediaSyncEvent createEvent(int eventType) 56505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent throws IllegalArgumentException { 57505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent if (!isValidType(eventType)) { 58505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent throw (new IllegalArgumentException(eventType 59505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent + "is not a valid MediaSyncEvent type.")); 60505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } else { 61505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent return new MediaSyncEvent(eventType); 62505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } 63505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } 64505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 65505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent private final int mType; 66505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent private int mAudioSession = 0; 67505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 68505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent private MediaSyncEvent(int eventType) { 69505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent mType = eventType; 70505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } 71505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 72505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent /** 73505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * Sets the event source audio session ID. 74505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * 75505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * <p>The audio session ID specifies on which audio session the synchronization event should be 76505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * monitored. 77505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * It is mandatory for certain event types (e.g. {@link #SYNC_EVENT_PRESENTATION_COMPLETE}). 78505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * For instance, the audio session ID can be retrieved via 79505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * {@link MediaPlayer#getAudioSessionId()} when monitoring an event on a particular MediaPlayer. 80505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * @param audioSessionId the audio session ID of the event source being monitored. 81505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * @return the MediaSyncEvent the method is called on. 82505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * @throws java.lang.IllegalArgumentException 83505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent */ 84505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent public MediaSyncEvent setAudioSessionId(int audioSessionId) 85505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent throws IllegalArgumentException { 86505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent if (audioSessionId > 0) { 87505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent mAudioSession = audioSessionId; 88505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } else { 89505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent throw (new IllegalArgumentException(audioSessionId + " is not a valid session ID.")); 90505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } 91505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent return this; 92505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } 93505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 94505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent /** 95505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * Gets the synchronization event type. 96505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * 97505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * @return the synchronization event type. 98505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent */ 99505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent public int getType() { 100505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent return mType; 101505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } 102505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 103505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent /** 104505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * Gets the synchronization event audio session ID. 105505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * 106505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * @return the synchronization audio session ID. The returned audio session ID is 0 if it has 107505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent * not been set. 108505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent */ 109505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent public int getAudioSessionId() { 110505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent return mAudioSession; 111505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } 112505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent 113505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent private static boolean isValidType(int type) { 114505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent switch (type) { 115505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent case SYNC_EVENT_NONE: 116505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent case SYNC_EVENT_PRESENTATION_COMPLETE: 117505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent return true; 118505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent default: 119505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent return false; 120505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } 121505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent } 122505e5c8859f596ed58489be565d6e029314b2ac8Eric Laurent} 123