TvTrackInfo.java revision 24ed8072f5b7f221c5b69ff8216ff77b06f506e6
1/* 2 * Copyright (C) 2014 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.tv; 18 19import android.os.Bundle; 20import android.os.Parcel; 21import android.os.Parcelable; 22 23/** 24 * Encapsulates the format of tracks played in {@link TvInputService}. 25 */ 26public final class TvTrackInfo implements Parcelable { 27 /** 28 * The type value for audio tracks. 29 */ 30 public static final int TYPE_AUDIO = 0; 31 32 /** 33 * The type value for video tracks. 34 */ 35 public static final int TYPE_VIDEO = 1; 36 37 /** 38 * The type value for subtitle tracks. 39 */ 40 public static final int TYPE_SUBTITLE = 2; 41 42 private final int mType; 43 private final String mId; 44 private final String mLanguage; 45 private final String mDescription; 46 private final int mAudioChannelCount; 47 private final int mAudioSampleRate; 48 private final int mVideoWidth; 49 private final int mVideoHeight; 50 private final float mVideoFrameRate; 51 private final float mVideoPixelAspectRatio; 52 private final Bundle mExtra; 53 54 private TvTrackInfo(int type, String id, String language, String description, 55 int audioChannelCount, int audioSampleRate, int videoWidth, int videoHeight, 56 float videoFrameRate, float videoPixelAspectRatio, Bundle extra) { 57 mType = type; 58 mId = id; 59 mLanguage = language; 60 mDescription = description; 61 mAudioChannelCount = audioChannelCount; 62 mAudioSampleRate = audioSampleRate; 63 mVideoWidth = videoWidth; 64 mVideoHeight = videoHeight; 65 mVideoFrameRate = videoFrameRate; 66 mVideoPixelAspectRatio = videoPixelAspectRatio; 67 mExtra = extra; 68 } 69 70 private TvTrackInfo(Parcel in) { 71 mType = in.readInt(); 72 mId = in.readString(); 73 mLanguage = in.readString(); 74 mDescription = in.readString(); 75 mAudioChannelCount = in.readInt(); 76 mAudioSampleRate = in.readInt(); 77 mVideoWidth = in.readInt(); 78 mVideoHeight = in.readInt(); 79 mVideoFrameRate = in.readFloat(); 80 mVideoPixelAspectRatio = in.readFloat(); 81 mExtra = in.readBundle(); 82 } 83 84 /** 85 * Returns the type of the track. The type should be one of the followings: 86 * {@link #TYPE_AUDIO}, {@link #TYPE_VIDEO} and {@link #TYPE_SUBTITLE}. 87 */ 88 public final int getType() { 89 return mType; 90 } 91 92 /** 93 * Returns the ID of the track. 94 */ 95 public final String getId() { 96 return mId; 97 } 98 99 /** 100 * Returns the language information encoded by either ISO 639-1 or ISO 639-2/T. If the language 101 * is unknown or could not be determined, the corresponding value will be {@code null}. 102 */ 103 public final String getLanguage() { 104 return mLanguage; 105 } 106 107 /** 108 * Returns a user readable description for the current track. 109 */ 110 public final String getDescription() { 111 return mDescription; 112 } 113 114 /** 115 * Returns the audio channel count. Valid only for {@link #TYPE_AUDIO} tracks. 116 */ 117 public final int getAudioChannelCount() { 118 if (mType != TYPE_AUDIO) { 119 throw new IllegalStateException("Not an audio track"); 120 } 121 return mAudioChannelCount; 122 } 123 124 /** 125 * Returns the audio sample rate, in the unit of Hz. Valid only for {@link #TYPE_AUDIO} tracks. 126 */ 127 public final int getAudioSampleRate() { 128 if (mType != TYPE_AUDIO) { 129 throw new IllegalStateException("Not an audio track"); 130 } 131 return mAudioSampleRate; 132 } 133 134 /** 135 * Returns the width of the video, in the unit of pixels. Valid only for {@link #TYPE_VIDEO} 136 * tracks. 137 */ 138 public final int getVideoWidth() { 139 if (mType != TYPE_VIDEO) { 140 throw new IllegalStateException("Not a video track"); 141 } 142 return mVideoWidth; 143 } 144 145 /** 146 * Returns the height of the video, in the unit of pixels. Valid only for {@link #TYPE_VIDEO} 147 * tracks. 148 */ 149 public final int getVideoHeight() { 150 if (mType != TYPE_VIDEO) { 151 throw new IllegalStateException("Not a video track"); 152 } 153 return mVideoHeight; 154 } 155 156 /** 157 * Returns the frame rate of the video, in the unit of fps (frames per second). Valid only for 158 * {@link #TYPE_VIDEO} tracks. 159 */ 160 public final float getVideoFrameRate() { 161 if (mType != TYPE_VIDEO) { 162 throw new IllegalStateException("Not a video track"); 163 } 164 return mVideoFrameRate; 165 } 166 167 /** 168 * Returns the pixel aspect ratio (the ratio of a pixel's width to its height) of the video. 169 * Valid only for {@link #TYPE_VIDEO} tracks. 170 */ 171 public final float getVideoPixelAspectRatio() { 172 if (mType != TYPE_VIDEO) { 173 throw new IllegalStateException("Not a video track"); 174 } 175 return mVideoPixelAspectRatio; 176 } 177 178 /** 179 * Returns the extra information about the current track. 180 */ 181 public final Bundle getExtra() { 182 return mExtra; 183 } 184 185 @Override 186 public int describeContents() { 187 return 0; 188 } 189 190 /** 191 * Used to package this object into a {@link Parcel}. 192 * 193 * @param dest The {@link Parcel} to be written. 194 * @param flags The flags used for parceling. 195 */ 196 @Override 197 public void writeToParcel(Parcel dest, int flags) { 198 dest.writeInt(mType); 199 dest.writeString(mId); 200 dest.writeString(mLanguage); 201 dest.writeString(mDescription); 202 dest.writeInt(mAudioChannelCount); 203 dest.writeInt(mAudioSampleRate); 204 dest.writeInt(mVideoWidth); 205 dest.writeInt(mVideoHeight); 206 dest.writeFloat(mVideoFrameRate); 207 dest.writeFloat(mVideoPixelAspectRatio); 208 dest.writeBundle(mExtra); 209 } 210 211 public static final Parcelable.Creator<TvTrackInfo> CREATOR = 212 new Parcelable.Creator<TvTrackInfo>() { 213 @Override 214 public TvTrackInfo createFromParcel(Parcel in) { 215 return new TvTrackInfo(in); 216 } 217 218 @Override 219 public TvTrackInfo[] newArray(int size) { 220 return new TvTrackInfo[size]; 221 } 222 }; 223 224 /** 225 * A builder class for creating {@link TvTrackInfo} objects. 226 */ 227 public static final class Builder { 228 private final String mId; 229 private final int mType; 230 private String mLanguage; 231 private String mDescription; 232 private int mAudioChannelCount; 233 private int mAudioSampleRate; 234 private int mVideoWidth; 235 private int mVideoHeight; 236 private float mVideoFrameRate; 237 private float mVideoPixelAspectRatio = 1.0f; 238 private Bundle mExtra; 239 240 /** 241 * Create a {@link Builder}. Any field that should be included in the {@link TvTrackInfo} 242 * must be added. 243 * 244 * @param type The type of the track. 245 * @param id The ID of the track that uniquely identifies the current track among all the 246 * other tracks in the same TV program. 247 */ 248 public Builder(int type, String id) { 249 if (type != TYPE_AUDIO 250 && type != TYPE_VIDEO 251 && type != TYPE_SUBTITLE) { 252 throw new IllegalArgumentException("Unknown type: " + type); 253 } 254 if (id == null) { 255 throw new IllegalArgumentException("id cannot be null"); 256 } 257 mType = type; 258 mId = id; 259 } 260 261 /** 262 * Sets the language information of the current track. 263 * 264 * @param language The language string encoded by either ISO 639-1 or ISO 639-2/T. 265 */ 266 public final Builder setLanguage(String language) { 267 mLanguage = language; 268 return this; 269 } 270 271 /** 272 * Sets a user readable description for the current track. 273 * 274 * @param description The user readable description. 275 */ 276 public final Builder setDescription(String description) { 277 mDescription = description; 278 return this; 279 } 280 281 /** 282 * Sets the audio channel count. Valid only for {@link #TYPE_AUDIO} tracks. 283 * 284 * @param audioChannelCount The audio channel count. 285 */ 286 public final Builder setAudioChannelCount(int audioChannelCount) { 287 if (mType != TYPE_AUDIO) { 288 throw new IllegalStateException("Not an audio track"); 289 } 290 mAudioChannelCount = audioChannelCount; 291 return this; 292 } 293 294 /** 295 * Sets the audio sample rate, in the unit of Hz. Valid only for {@link #TYPE_AUDIO} 296 * tracks. 297 * 298 * @param audioSampleRate The audio sample rate. 299 */ 300 public final Builder setAudioSampleRate(int audioSampleRate) { 301 if (mType != TYPE_AUDIO) { 302 throw new IllegalStateException("Not an audio track"); 303 } 304 mAudioSampleRate = audioSampleRate; 305 return this; 306 } 307 308 /** 309 * Sets the width of the video, in the unit of pixels. Valid only for {@link #TYPE_VIDEO} 310 * tracks. 311 * 312 * @param videoWidth The width of the video. 313 */ 314 public final Builder setVideoWidth(int videoWidth) { 315 if (mType != TYPE_VIDEO) { 316 throw new IllegalStateException("Not a video track"); 317 } 318 mVideoWidth = videoWidth; 319 return this; 320 } 321 322 /** 323 * Sets the height of the video, in the unit of pixels. Valid only for {@link #TYPE_VIDEO} 324 * tracks. 325 * 326 * @param videoHeight The height of the video. 327 */ 328 public final Builder setVideoHeight(int videoHeight) { 329 if (mType != TYPE_VIDEO) { 330 throw new IllegalStateException("Not a video track"); 331 } 332 mVideoHeight = videoHeight; 333 return this; 334 } 335 336 /** 337 * Sets the frame rate of the video, in the unit fps (frames per rate). Valid only for 338 * {@link #TYPE_VIDEO} tracks. 339 * 340 * @param videoFrameRate The frame rate of the video. 341 */ 342 public final Builder setVideoFrameRate(float videoFrameRate) { 343 if (mType != TYPE_VIDEO) { 344 throw new IllegalStateException("Not a video track"); 345 } 346 mVideoFrameRate = videoFrameRate; 347 return this; 348 } 349 350 /** 351 * Sets the pixel aspect ratio (the ratio of a pixel's width to its height) of the video. 352 * Valid only for {@link #TYPE_VIDEO} tracks. 353 * <p> 354 * This is needed for applications to be able to scale the video properly for some video 355 * formats such as 720x576 4:3 and 720x576 16:9 where pixels are not square. By default, 356 * applications assume the value of 1.0 (square pixels), so it is not necessary to set the 357 * pixel aspect ratio for most video formats. 358 * </p> 359 * 360 * @param videoPixelAspectRatio The pixel aspect ratio of the video. 361 */ 362 public final Builder setVideoPixelAspectRatio(float videoPixelAspectRatio) { 363 if (mType != TYPE_VIDEO) { 364 throw new IllegalStateException("Not a video track"); 365 } 366 mVideoPixelAspectRatio = videoPixelAspectRatio; 367 return this; 368 } 369 370 /** 371 * Sets the extra information about the current track. 372 * 373 * @param extra The extra information. 374 */ 375 public final Builder setExtra(Bundle extra) { 376 mExtra = new Bundle(extra); 377 return this; 378 } 379 380 /** 381 * Creates a {@link TvTrackInfo} instance with the specified fields. 382 * 383 * @return The new {@link TvTrackInfo} instance 384 */ 385 public TvTrackInfo build() { 386 return new TvTrackInfo(mType, mId, mLanguage, mDescription, mAudioChannelCount, 387 mAudioSampleRate, mVideoWidth, mVideoHeight, mVideoFrameRate, 388 mVideoPixelAspectRatio, mExtra); 389 } 390 } 391} 392