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