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 17 package 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 */ 27 public class MediaSyncEvent { 28 29 /** 30 * No sync event specified. When used with a synchronized playback or capture method, the 31 * behavior is equivalent to calling the corresponding non synchronized method. 32 */ 33 public static final int SYNC_EVENT_NONE = AudioSystem.SYNC_EVENT_NONE; 34 35 /** 36 * The corresponding action is triggered only when the presentation is completed 37 * (meaning the media has been presented to the user) on the specified session. 38 * A synchronization of this type requires a source audio session ID to be set via 39 * {@link #setAudioSessionId(int) method. 40 */ 41 public static final int SYNC_EVENT_PRESENTATION_COMPLETE = 42 AudioSystem.SYNC_EVENT_PRESENTATION_COMPLETE; 43 44 45 /** 46 * Creates a synchronization event of the sepcified type. 47 * 48 * <p>The type specifies which kind of event is monitored. 49 * For instance, event {@link #SYNC_EVENT_PRESENTATION_COMPLETE} corresponds to the audio being 50 * presented to the user on a particular audio session. 51 * @param eventType the synchronization event type. 52 * @return the MediaSyncEvent created. 53 * @throws java.lang.IllegalArgumentException 54 */ 55 public static MediaSyncEvent createEvent(int eventType) 56 throws IllegalArgumentException { 57 if (!isValidType(eventType)) { 58 throw (new IllegalArgumentException(eventType 59 + "is not a valid MediaSyncEvent type.")); 60 } else { 61 return new MediaSyncEvent(eventType); 62 } 63 } 64 65 private final int mType; 66 private int mAudioSession = 0; 67 68 private MediaSyncEvent(int eventType) { 69 mType = eventType; 70 } 71 72 /** 73 * Sets the event source audio session ID. 74 * 75 * <p>The audio session ID specifies on which audio session the synchronization event should be 76 * monitored. 77 * It is mandatory for certain event types (e.g. {@link #SYNC_EVENT_PRESENTATION_COMPLETE}). 78 * For instance, the audio session ID can be retrieved via 79 * {@link MediaPlayer#getAudioSessionId()} when monitoring an event on a particular MediaPlayer. 80 * @param audioSessionId the audio session ID of the event source being monitored. 81 * @return the MediaSyncEvent the method is called on. 82 * @throws java.lang.IllegalArgumentException 83 */ 84 public MediaSyncEvent setAudioSessionId(int audioSessionId) 85 throws IllegalArgumentException { 86 if (audioSessionId > 0) { 87 mAudioSession = audioSessionId; 88 } else { 89 throw (new IllegalArgumentException(audioSessionId + " is not a valid session ID.")); 90 } 91 return this; 92 } 93 94 /** 95 * Gets the synchronization event type. 96 * 97 * @return the synchronization event type. 98 */ 99 public int getType() { 100 return mType; 101 } 102 103 /** 104 * Gets the synchronization event audio session ID. 105 * 106 * @return the synchronization audio session ID. The returned audio session ID is 0 if it has 107 * not been set. 108 */ 109 public int getAudioSessionId() { 110 return mAudioSession; 111 } 112 113 private static boolean isValidType(int type) { 114 switch (type) { 115 case SYNC_EVENT_NONE: 116 case SYNC_EVENT_PRESENTATION_COMPLETE: 117 return true; 118 default: 119 return false; 120 } 121 } 122 } 123