1 /* 2 * Copyright (C) 2016 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 package com.google.android.exoplayer2.extractor; 17 18 import androidx.annotation.IntDef; 19 import androidx.annotation.Nullable; 20 import com.google.android.exoplayer2.C; 21 import com.google.android.exoplayer2.Format; 22 import com.google.android.exoplayer2.upstream.DataReader; 23 import com.google.android.exoplayer2.util.ParsableByteArray; 24 import java.io.EOFException; 25 import java.io.IOException; 26 import java.lang.annotation.Documented; 27 import java.lang.annotation.Retention; 28 import java.lang.annotation.RetentionPolicy; 29 import java.util.Arrays; 30 31 /** 32 * Receives track level data extracted by an {@link Extractor}. 33 */ 34 public interface TrackOutput { 35 36 /** 37 * Holds data required to decrypt a sample. 38 */ 39 final class CryptoData { 40 41 /** 42 * The encryption mode used for the sample. 43 */ 44 @C.CryptoMode public final int cryptoMode; 45 46 /** 47 * The encryption key associated with the sample. Its contents must not be modified. 48 */ 49 public final byte[] encryptionKey; 50 51 /** 52 * The number of encrypted blocks in the encryption pattern, 0 if pattern encryption does not 53 * apply. 54 */ 55 public final int encryptedBlocks; 56 57 /** 58 * The number of clear blocks in the encryption pattern, 0 if pattern encryption does not 59 * apply. 60 */ 61 public final int clearBlocks; 62 63 /** 64 * @param cryptoMode See {@link #cryptoMode}. 65 * @param encryptionKey See {@link #encryptionKey}. 66 * @param encryptedBlocks See {@link #encryptedBlocks}. 67 * @param clearBlocks See {@link #clearBlocks}. 68 */ CryptoData(@.CryptoMode int cryptoMode, byte[] encryptionKey, int encryptedBlocks, int clearBlocks)69 public CryptoData(@C.CryptoMode int cryptoMode, byte[] encryptionKey, int encryptedBlocks, 70 int clearBlocks) { 71 this.cryptoMode = cryptoMode; 72 this.encryptionKey = encryptionKey; 73 this.encryptedBlocks = encryptedBlocks; 74 this.clearBlocks = clearBlocks; 75 } 76 77 @Override equals(@ullable Object obj)78 public boolean equals(@Nullable Object obj) { 79 if (this == obj) { 80 return true; 81 } 82 if (obj == null || getClass() != obj.getClass()) { 83 return false; 84 } 85 CryptoData other = (CryptoData) obj; 86 return cryptoMode == other.cryptoMode && encryptedBlocks == other.encryptedBlocks 87 && clearBlocks == other.clearBlocks && Arrays.equals(encryptionKey, other.encryptionKey); 88 } 89 90 @Override hashCode()91 public int hashCode() { 92 int result = cryptoMode; 93 result = 31 * result + Arrays.hashCode(encryptionKey); 94 result = 31 * result + encryptedBlocks; 95 result = 31 * result + clearBlocks; 96 return result; 97 } 98 99 } 100 101 /** Defines the part of the sample data to which a call to {@link #sampleData} corresponds. */ 102 @Documented 103 @Retention(RetentionPolicy.SOURCE) 104 @IntDef({SAMPLE_DATA_PART_MAIN, SAMPLE_DATA_PART_ENCRYPTION, SAMPLE_DATA_PART_SUPPLEMENTAL}) 105 @interface SampleDataPart {} 106 107 /** Main media sample data. */ 108 int SAMPLE_DATA_PART_MAIN = 0; 109 /** 110 * Sample encryption data. 111 * 112 * <p>The format for encryption information is: 113 * 114 * <ul> 115 * <li>(1 byte) {@code encryption_signal_byte}: Most significant bit signals whether the 116 * encryption data contains subsample encryption data. The remaining bits contain {@code 117 * initialization_vector_size}. 118 * <li>({@code initialization_vector_size} bytes) Initialization vector. 119 * <li>If subsample encryption data is present, as per {@code encryption_signal_byte}, the 120 * encryption data also contains: 121 * <ul> 122 * <li>(2 bytes) {@code subsample_encryption_data_length}. 123 * <li>({@code subsample_encryption_data_length} bytes) Subsample encryption data 124 * (repeated {@code subsample_encryption_data_length / 6} times: 125 * <ul> 126 * <li>(3 bytes) Size of a clear section in sample. 127 * <li>(3 bytes) Size of an encryption section in sample. 128 * </ul> 129 * </ul> 130 * </ul> 131 */ 132 int SAMPLE_DATA_PART_ENCRYPTION = 1; 133 /** Sample supplemental data. */ 134 int SAMPLE_DATA_PART_SUPPLEMENTAL = 2; 135 136 /** 137 * Called when the {@link Format} of the track has been extracted from the stream. 138 * 139 * @param format The extracted {@link Format}. 140 */ format(Format format)141 void format(Format format); 142 143 /** 144 * Equivalent to {@link #sampleData(DataReader, int, boolean, int) sampleData(input, length, 145 * allowEndOfInput, SAMPLE_DATA_PART_MAIN)}. 146 */ sampleData(DataReader input, int length, boolean allowEndOfInput)147 default int sampleData(DataReader input, int length, boolean allowEndOfInput) throws IOException { 148 return sampleData(input, length, allowEndOfInput, SAMPLE_DATA_PART_MAIN); 149 } 150 151 /** 152 * Equivalent to {@link #sampleData(ParsableByteArray, int, int)} sampleData(data, length, 153 * SAMPLE_DATA_PART_MAIN)}. 154 */ sampleData(ParsableByteArray data, int length)155 default void sampleData(ParsableByteArray data, int length) { 156 sampleData(data, length, SAMPLE_DATA_PART_MAIN); 157 } 158 159 /** 160 * Called to write sample data to the output. 161 * 162 * @param input A {@link DataReader} from which to read the sample data. 163 * @param length The maximum length to read from the input. 164 * @param allowEndOfInput True if encountering the end of the input having read no data is 165 * allowed, and should result in {@link C#RESULT_END_OF_INPUT} being returned. False if it 166 * should be considered an error, causing an {@link EOFException} to be thrown. 167 * @param sampleDataPart The part of the sample data to which this call corresponds. 168 * @return The number of bytes appended. 169 * @throws IOException If an error occurred reading from the input. 170 */ sampleData( DataReader input, int length, boolean allowEndOfInput, @SampleDataPart int sampleDataPart)171 int sampleData( 172 DataReader input, int length, boolean allowEndOfInput, @SampleDataPart int sampleDataPart) 173 throws IOException; 174 175 /** 176 * Called to write sample data to the output. 177 * 178 * @param data A {@link ParsableByteArray} from which to read the sample data. 179 * @param length The number of bytes to read, starting from {@code data.getPosition()}. 180 * @param sampleDataPart The part of the sample data to which this call corresponds. 181 */ sampleData(ParsableByteArray data, int length, @SampleDataPart int sampleDataPart)182 void sampleData(ParsableByteArray data, int length, @SampleDataPart int sampleDataPart); 183 184 /** 185 * Called when metadata associated with a sample has been extracted from the stream. 186 * 187 * <p>The corresponding sample data will have already been passed to the output via calls to 188 * {@link #sampleData(DataReader, int, boolean)} or {@link #sampleData(ParsableByteArray, int)}. 189 * 190 * @param timeUs The media timestamp associated with the sample, in microseconds. 191 * @param flags Flags associated with the sample. See {@code C.BUFFER_FLAG_*}. 192 * @param size The size of the sample data, in bytes. 193 * @param offset The number of bytes that have been passed to {@link #sampleData(DataReader, int, 194 * boolean)} or {@link #sampleData(ParsableByteArray, int)} since the last byte belonging to 195 * the sample whose metadata is being passed. 196 * @param encryptionData The encryption data required to decrypt the sample. May be null. 197 */ sampleMetadata( long timeUs, @C.BufferFlags int flags, int size, int offset, @Nullable CryptoData encryptionData)198 void sampleMetadata( 199 long timeUs, 200 @C.BufferFlags int flags, 201 int size, 202 int offset, 203 @Nullable CryptoData encryptionData); 204 } 205