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 int mAudioChannelCount;
46    private final int mAudioSampleRate;
47    private final int mVideoWidth;
48    private final int mVideoHeight;
49    private final float mVideoFrameRate;
50    private final Bundle mExtra;
51
52    private TvTrackInfo(int type, String id, String language, int audioChannelCount,
53            int audioSampleRate, int videoWidth, int videoHeight, float videoFrameRate,
54            Bundle extra) {
55        mType = type;
56        mId = id;
57        mLanguage = language;
58        mAudioChannelCount = audioChannelCount;
59        mAudioSampleRate = audioSampleRate;
60        mVideoWidth = videoWidth;
61        mVideoHeight = videoHeight;
62        mVideoFrameRate = videoFrameRate;
63        mExtra = extra;
64    }
65
66    private TvTrackInfo(Parcel in) {
67        mType = in.readInt();
68        mId = in.readString();
69        mLanguage = in.readString();
70        mAudioChannelCount = in.readInt();
71        mAudioSampleRate = in.readInt();
72        mVideoWidth = in.readInt();
73        mVideoHeight = in.readInt();
74        mVideoFrameRate = in.readFloat();
75        mExtra = in.readBundle();
76    }
77
78    /**
79     * Returns the type of the track. The type should be one of the followings:
80     * {@link #TYPE_AUDIO}, {@link #TYPE_VIDEO} and {@link #TYPE_SUBTITLE}.
81     */
82    public final int getType() {
83        return mType;
84    }
85
86    /**
87     * Returns the ID of the track.
88     */
89    public final String getId() {
90        return mId;
91    }
92
93    /**
94     * Returns the language information encoded by either ISO 639-1 or ISO 639-2/T. If the language
95     * is unknown or could not be determined, the corresponding value will be {@code null}.
96     */
97    public final String getLanguage() {
98        return mLanguage;
99    }
100
101    /**
102     * Returns the audio channel count. Valid only for {@link #TYPE_AUDIO} tracks.
103     */
104    public final int getAudioChannelCount() {
105        if (mType != TYPE_AUDIO) {
106            throw new IllegalStateException("Not an audio track");
107        }
108        return mAudioChannelCount;
109    }
110
111    /**
112     * Returns the audio sample rate, in the unit of Hz. Valid only for {@link #TYPE_AUDIO} tracks.
113     */
114    public final int getAudioSampleRate() {
115        if (mType != TYPE_AUDIO) {
116            throw new IllegalStateException("Not an audio track");
117        }
118        return mAudioSampleRate;
119    }
120
121    /**
122     * Returns the width of the video, in the unit of pixels. Valid only for {@link #TYPE_VIDEO}
123     * tracks.
124     */
125    public final int getVideoWidth() {
126        if (mType != TYPE_VIDEO) {
127            throw new IllegalStateException("Not a video track");
128        }
129        return mVideoWidth;
130    }
131
132    /**
133     * Returns the height of the video, in the unit of pixels. Valid only for {@link #TYPE_VIDEO}
134     * tracks.
135     */
136    public final int getVideoHeight() {
137        if (mType != TYPE_VIDEO) {
138            throw new IllegalStateException("Not a video track");
139        }
140        return mVideoHeight;
141    }
142
143    /**
144     * Returns the frame rate of the video, in the unit of fps (frames per second). Valid only for
145     * {@link #TYPE_VIDEO} tracks.
146     */
147    public final float getVideoFrameRate() {
148        if (mType != TYPE_VIDEO) {
149            throw new IllegalStateException("Not a video track");
150        }
151        return mVideoFrameRate;
152    }
153
154    /**
155     * Returns the extra information about the current track.
156     */
157    public final Bundle getExtra() {
158        return mExtra;
159    }
160
161    @Override
162    public int describeContents() {
163        return 0;
164    }
165
166    /**
167     * Used to package this object into a {@link Parcel}.
168     *
169     * @param dest The {@link Parcel} to be written.
170     * @param flags The flags used for parceling.
171     */
172    @Override
173    public void writeToParcel(Parcel dest, int flags) {
174        dest.writeInt(mType);
175        dest.writeString(mId);
176        dest.writeString(mLanguage);
177        dest.writeInt(mAudioChannelCount);
178        dest.writeInt(mAudioSampleRate);
179        dest.writeInt(mVideoWidth);
180        dest.writeInt(mVideoHeight);
181        dest.writeFloat(mVideoFrameRate);
182        dest.writeBundle(mExtra);
183    }
184
185    public static final Parcelable.Creator<TvTrackInfo> CREATOR =
186            new Parcelable.Creator<TvTrackInfo>() {
187                @Override
188                public TvTrackInfo createFromParcel(Parcel in) {
189                    return new TvTrackInfo(in);
190                }
191
192                @Override
193                public TvTrackInfo[] newArray(int size) {
194                    return new TvTrackInfo[size];
195                }
196            };
197
198    /**
199     * A builder class for creating {@link TvTrackInfo} objects.
200     */
201    public static final class Builder {
202        private final String mId;
203        private final int mType;
204        private String mLanguage;
205        private int mAudioChannelCount;
206        private int mAudioSampleRate;
207        private int mVideoWidth;
208        private int mVideoHeight;
209        private float mVideoFrameRate;
210        private Bundle mExtra;
211
212        /**
213         * Create a {@link Builder}. Any field that should be included in the {@link TvTrackInfo}
214         * must be added.
215         *
216         * @param type The type of the track.
217         * @param id The ID of the track that uniquely identifies the current track among all the
218         *            other tracks in the same TV program.
219         */
220        public Builder(int type, String id) {
221            if (type != TYPE_AUDIO
222                    && type != TYPE_VIDEO
223                    && type != TYPE_SUBTITLE) {
224                throw new IllegalArgumentException("Unknown type: " + type);
225            }
226            if (id == null) {
227                throw new IllegalArgumentException("id cannot be null");
228            }
229            mType = type;
230            mId = id;
231        }
232
233        /**
234         * Sets the language information of the current track.
235         *
236         * @param language The language string encoded by either ISO 639-1 or ISO 639-2/T.
237         */
238        public final Builder setLanguage(String language) {
239            mLanguage = language;
240            return this;
241        }
242
243        /**
244         * Sets the audio channel count. Valid only for {@link #TYPE_AUDIO} tracks.
245         *
246         * @param audioChannelCount The audio channel count.
247         */
248        public final Builder setAudioChannelCount(int audioChannelCount) {
249            if (mType != TYPE_AUDIO) {
250                throw new IllegalStateException("Not an audio track");
251            }
252            mAudioChannelCount = audioChannelCount;
253            return this;
254        }
255
256        /**
257         * Sets the audio sample rate, in the unit of Hz. Valid only for {@link #TYPE_AUDIO}
258         * tracks.
259         *
260         * @param audioSampleRate The audio sample rate.
261         */
262        public final Builder setAudioSampleRate(int audioSampleRate) {
263            if (mType != TYPE_AUDIO) {
264                throw new IllegalStateException("Not an audio track");
265            }
266            mAudioSampleRate = audioSampleRate;
267            return this;
268        }
269
270        /**
271         * Sets the width of the video, in the unit of pixels. Valid only for {@link #TYPE_VIDEO}
272         * tracks.
273         *
274         * @param videoWidth The width of the video.
275         */
276        public final Builder setVideoWidth(int videoWidth) {
277            if (mType != TYPE_VIDEO) {
278                throw new IllegalStateException("Not a video track");
279            }
280            mVideoWidth = videoWidth;
281            return this;
282        }
283
284        /**
285         * Sets the height of the video, in the unit of pixels. Valid only for {@link #TYPE_VIDEO}
286         * tracks.
287         *
288         * @param videoHeight The height of the video.
289         */
290        public final Builder setVideoHeight(int videoHeight) {
291            if (mType != TYPE_VIDEO) {
292                throw new IllegalStateException("Not a video track");
293            }
294            mVideoHeight = videoHeight;
295            return this;
296        }
297
298        /**
299         * Sets the frame rate of the video, in the unit fps (frames per rate). Valid only for
300         * {@link #TYPE_VIDEO} tracks.
301         *
302         * @param videoFrameRate The frame rate of the video.
303         */
304        public final Builder setVideoFrameRate(float videoFrameRate) {
305            if (mType != TYPE_VIDEO) {
306                throw new IllegalStateException("Not a video track");
307            }
308            mVideoFrameRate = videoFrameRate;
309            return this;
310        }
311
312        /**
313         * Sets the extra information about the current track.
314         *
315         * @param extra The extra information.
316         */
317        public final Builder setExtra(Bundle extra) {
318            mExtra = new Bundle(extra);
319            return this;
320        }
321
322        /**
323         * Creates a {@link TvTrackInfo} instance with the specified fields.
324         *
325         * @return The new {@link TvTrackInfo} instance
326         */
327        public TvTrackInfo build() {
328            return new TvTrackInfo(mType, mId, mLanguage, mAudioChannelCount, mAudioSampleRate,
329                    mVideoWidth, mVideoHeight, mVideoFrameRate, mExtra);
330        }
331    }
332}