Add track types to audio streams (#1041)

Author: Theta-Dev

extractor/src/main/java/org/schabi/newpipe/extractor/services/youtube/ItagItem.java

@@ -2,6 +2,7 @@
 
 import org.schabi.newpipe.extractor.MediaFormat;
 import org.schabi.newpipe.extractor.exceptions.ParsingException;
+import org.schabi.newpipe.extractor.stream.AudioTrackType;
 
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
@@ -201,7 +202,7 @@ public ItagItem(@Nonnull final ItagItem itagItem) {
         this.contentLength = itagItem.contentLength;
         this.audioTrackId = itagItem.audioTrackId;
         this.audioTrackName = itagItem.audioTrackName;
-        this.isDescriptiveAudio = itagItem.isDescriptiveAudio;
+        this.audioTrackType = itagItem.audioTrackType;
         this.audioLocale = itagItem.audioLocale;
     }
 
@@ -251,7 +252,8 @@ public MediaFormat getMediaFormat() {
     private long contentLength = CONTENT_LENGTH_UNKNOWN;
     private String audioTrackId;
     private String audioTrackName;
-    private boolean isDescriptiveAudio;
+    @Nullable
+    private AudioTrackType audioTrackType;
     @Nullable
     private Locale audioLocale;
 
@@ -594,21 +596,22 @@ public void setAudioTrackName(@Nullable final String audioTrackName) {
     }
 
     /**
-     * Return whether the stream is a descriptive audio.
+     * Get the {@link AudioTrackType} of the stream.
      *
-     * @return whether the stream is a descriptive audio
+     * @return the {@link AudioTrackType} of the stream or {@code null}
      */
-    public boolean isDescriptiveAudio() {
-        return isDescriptiveAudio;
+    @Nullable
+    public AudioTrackType getAudioTrackType() {
+        return audioTrackType;
     }
 
     /**
-     * Set whether the stream is a descriptive audio.
+     * Set the {@link AudioTrackType} of the stream, if present.
      *
-     * @param isDescriptiveAudio whether the stream is a descriptive audio
+     * @param audioTrackType the {@link AudioTrackType} of the stream or {@code null}
      */
-    public void setIsDescriptiveAudio(final boolean isDescriptiveAudio) {
-        this.isDescriptiveAudio = isDescriptiveAudio;
+    public void setAudioTrackType(@Nullable final AudioTrackType audioTrackType) {
+        this.audioTrackType = audioTrackType;
     }
 
     /**

extractor/src/main/java/org/schabi/newpipe/extractor/services/youtube/YoutubeParsingHelper.java

@@ -43,6 +43,7 @@
 import org.schabi.newpipe.extractor.localization.ContentCountry;
 import org.schabi.newpipe.extractor.localization.Localization;
 import org.schabi.newpipe.extractor.playlist.PlaylistInfo;
+import org.schabi.newpipe.extractor.stream.AudioTrackType;
 import org.schabi.newpipe.extractor.stream.Description;
 import org.schabi.newpipe.extractor.utils.JsonUtils;
 import org.schabi.newpipe.extractor.utils.Parser;
@@ -1801,4 +1802,49 @@ public static void setConsentAccepted(final boolean accepted) {
     public static boolean isConsentAccepted() {
         return consentAccepted;
     }
+
+    /**
+     * Extract the audio track type from a YouTube stream URL.
+     * <p>
+     * The track type is parsed from the {@code xtags} URL parameter
+     * (Example: {@code acont=original:lang=en}).
+     * </p>
+     * @param streamUrl YouTube stream URL
+     * @return {@link AudioTrackType} or {@code null} if no track type was found
+     */
+    @Nullable
+    public static AudioTrackType extractAudioTrackType(final String streamUrl) {
+        final String xtags;
+        try {
+            xtags = Utils.getQueryValue(new URL(streamUrl), "xtags");
+        } catch (final MalformedURLException e) {
+            return null;
+        }
+        if (xtags == null) {
+            return null;
+        }
+
+        String atype = null;
+        for (final String param : xtags.split(":")) {
+            final String[] kv = param.split("=", 2);
+            if (kv.length > 1 && kv[0].equals("acont")) {
+                atype = kv[1];
+                break;
+            }
+        }
+        if (atype == null) {
+            return null;
+        }
+
+        switch (atype) {
+            case "original":
+                return AudioTrackType.ORIGINAL;
+            case "dubbed":
+                return AudioTrackType.DUBBED;
+            case "descriptive":
+                return AudioTrackType.DESCRIPTIVE;
+            default:
+                return null;
+        }
+    }
 }

extractor/src/main/java/org/schabi/newpipe/extractor/services/youtube/dashmanifestcreators/YoutubeDashManifestCreatorsUtils.java

@@ -16,6 +16,7 @@
 import org.schabi.newpipe.extractor.exceptions.ExtractionException;
 import org.schabi.newpipe.extractor.services.youtube.DeliveryType;
 import org.schabi.newpipe.extractor.services.youtube.ItagItem;
+import org.schabi.newpipe.extractor.stream.AudioTrackType;
 import org.schabi.newpipe.extractor.utils.ManifestCreatorCache;
 import org.w3c.dom.Attr;
 import org.w3c.dom.DOMException;
@@ -31,6 +32,7 @@
 import java.util.Objects;
 
 import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 import javax.xml.XMLConstants;
 import javax.xml.parsers.DocumentBuilder;
 import javax.xml.parsers.DocumentBuilderFactory;
@@ -278,7 +280,8 @@ public static void generateAdaptationSetElement(@Nonnull final Document doc,
      *
      * <p>
      * {@code <Role schemeIdUri="urn:mpeg:DASH:role:2011" value="VALUE"/>}, where {@code VALUE} is
-     * {@code main} for videos and audios and {@code alternate} for descriptive audio
+     * {@code main} for videos and audios, {@code description} for descriptive audio and
+     * {@code dub} for dubbed audio.
      * </p>
      *
      * <p>
@@ -298,15 +301,36 @@ public static void generateRoleElement(@Nonnull final Document doc,
             final Element roleElement = doc.createElement(ROLE);
 
             setAttribute(roleElement, doc, "schemeIdUri", "urn:mpeg:DASH:role:2011");
-            setAttribute(roleElement, doc, "value", itagItem.isDescriptiveAudio()
-                    ? "alternate" : "main");
+            setAttribute(roleElement, doc, "value", getRoleValue(itagItem.getAudioTrackType()));
 
             adaptationSetElement.appendChild(roleElement);
         } catch (final DOMException e) {
             throw CreationException.couldNotAddElement(ROLE, e);
         }
     }
 
+    /**
+     * Get the value of the {@code <Role>} element based on the {@link AudioTrackType} attribute
+     * of a stream.
+     * @param trackType audio track type
+     * @return role value
+     */
+    private static String getRoleValue(@Nullable final AudioTrackType trackType) {
+        if (trackType != null) {
+            switch (trackType) {
+                case ORIGINAL:
+                    return "main";
+                case DUBBED:
+                    return "dub";
+                case DESCRIPTIVE:
+                    return "description";
+                default:
+                    return "alternate";
+            }
+        }
+        return "main";
+    }
+
     /**
      * Generate the {@code <Representation>} element, appended as a child of the
      * {@code <AdaptationSet>} element.

extractor/src/main/java/org/schabi/newpipe/extractor/services/youtube/extractors/YoutubeStreamExtractor.java

@@ -1311,7 +1311,7 @@ private java.util.function.Function<ItagInfo, AudioStream> getAudioStreamBuilder
                     .setAudioTrackId(itagItem.getAudioTrackId())
                     .setAudioTrackName(itagItem.getAudioTrackName())
                     .setAudioLocale(itagItem.getAudioLocale())
-                    .setIsDescriptive(itagItem.isDescriptiveAudio())
+                    .setAudioTrackType(itagItem.getAudioTrackType())
                     .setItagItem(itagItem);
 
             if (streamType == StreamType.LIVE_STREAM
@@ -1484,16 +1484,11 @@ private ItagInfo buildAndAddItagInfoToList(
                     itagItem.setAudioLocale(LocaleCompat.forLanguageTag(
                             audioTrackId.substring(0, audioTrackIdLastLocaleCharacter)));
                 }
+                itagItem.setAudioTrackType(YoutubeParsingHelper.extractAudioTrackType(streamUrl));
             }
 
             itagItem.setAudioTrackName(formatData.getObject("audioTrack")
                     .getString("displayName"));
-
-            // Descriptive audio tracks
-            // This information is also provided as a protobuf object in the formatData
-            itagItem.setIsDescriptiveAudio(streamUrl.contains("acont%3Ddescriptive")
-                    // Support "decoded" URLs
-                    || streamUrl.contains("acont=descriptive"));
         }
 
         // YouTube return the content length and the approximate duration as strings

extractor/src/main/java/org/schabi/newpipe/extractor/stream/AudioStream.java

@@ -50,7 +50,8 @@ public final class AudioStream extends Stream {
     private final String audioTrackName;
     @Nullable
     private final Locale audioLocale;
-    private final boolean isDescriptive;
+    @Nullable
+    private final AudioTrackType audioTrackType;
 
     @Nullable
     private ItagItem itagItem;
@@ -75,7 +76,8 @@ public static final class Builder {
         private String audioTrackName;
         @Nullable
         private Locale audioLocale;
-        private boolean isDescriptive;
+        @Nullable
+        private AudioTrackType audioTrackType;
         @Nullable
         private ItagItem itagItem;
 
@@ -223,25 +225,17 @@ public Builder setAudioTrackName(@Nullable final String audioTrackName) {
         }
 
         /**
-         * Set whether this {@link AudioStream} is a descriptive audio.
-         *
-         * <p>
-         * A descriptive audio is an audio in which descriptions of visual elements of a video are
-         * added in the original audio, with the goal to make a video more accessible to blind and
-         * visually impaired people.
-         * </p>
+         * Set the {@link AudioTrackType} of the {@link AudioStream}.
          *
          * <p>
-         * The default value is {@code false}.
+         * The default value is {@code null}.
          * </p>
          *
-         * @param isDescriptive whether this {@link AudioStream} is a descriptive audio
+         * @param audioTrackType the audio track type of the {@link AudioStream}, which can be null
          * @return this {@link Builder} instance
-         * @see <a href="https://en.wikipedia.org/wiki/Audio_description">
-         *     https://en.wikipedia.org/wiki/Audio_description</a>
          */
-        public Builder setIsDescriptive(final boolean isDescriptive) {
-            this.isDescriptive = isDescriptive;
+        public Builder setAudioTrackType(final AudioTrackType audioTrackType) {
+            this.audioTrackType = audioTrackType;
             return this;
         }
 
@@ -313,7 +307,7 @@ public AudioStream build() {
             }
 
             return new AudioStream(id, content, isUrl, mediaFormat, deliveryMethod, averageBitrate,
-                    manifestUrl, audioTrackId, audioTrackName, audioLocale, isDescriptive,
+                    manifestUrl, audioTrackId, audioTrackName, audioLocale, audioTrackType,
                     itagItem);
         }
     }
@@ -350,7 +344,7 @@ private AudioStream(@Nonnull final String id,
                         @Nullable final String audioTrackId,
                         @Nullable final String audioTrackName,
                         @Nullable final Locale audioLocale,
-                        final boolean isDescriptive,
+                        @Nullable final AudioTrackType audioTrackType,
                         @Nullable final ItagItem itagItem) {
         super(id, content, isUrl, format, deliveryMethod, manifestUrl);
         if (itagItem != null) {
@@ -368,7 +362,7 @@ private AudioStream(@Nonnull final String id,
         this.audioTrackId = audioTrackId;
         this.audioTrackName = audioTrackName;
         this.audioLocale = audioLocale;
-        this.isDescriptive = isDescriptive;
+        this.audioTrackType = audioTrackType;
     }
 
     /**
@@ -379,7 +373,7 @@ public boolean equalStats(final Stream cmp) {
         return super.equalStats(cmp) && cmp instanceof AudioStream
                 && averageBitrate == ((AudioStream) cmp).averageBitrate
                 && Objects.equals(audioTrackId, ((AudioStream) cmp).audioTrackId)
-                && isDescriptive == ((AudioStream) cmp).isDescriptive
+                && audioTrackType == ((AudioStream) cmp).audioTrackType
                 && Objects.equals(audioLocale, ((AudioStream) cmp).audioLocale);
     }
 
@@ -507,20 +501,14 @@ public Locale getAudioLocale() {
     }
 
     /**
-     * Returns whether this stream is a descriptive audio.
+     * Get the {@link AudioTrackType} of the stream, which is {@code null} if the track type
+     * is not known.
      *
-     * <p>
-     * A descriptive audio is an audio in which descriptions of visual elements of a video are
-     * added in the original audio, with the goal to make a video more accessible to blind and
-     * visually impaired people.
-     * </p>
-     *
-     * @return {@code true} this audio stream is a descriptive audio, {@code false} otherwise
-     * @see <a href="https://en.wikipedia.org/wiki/Audio_description">
-     *     https://en.wikipedia.org/wiki/Audio_description</a>
+     * @return the {@link AudioTrackType} of the stream or {@code null}
      */
-    public boolean isDescriptive() {
-        return isDescriptive;
+    @Nullable
+    public AudioTrackType getAudioTrackType() {
+        return audioTrackType;
     }
 
     /**

extractor/src/main/java/org/schabi/newpipe/extractor/stream/AudioTrackType.java

@@ -0,0 +1,33 @@
+package org.schabi.newpipe.extractor.stream;
+
+/**
+ * An enum representing the track type of an {@link AudioStream} extracted by a {@link
+ * StreamExtractor}.
+ */
+public enum AudioTrackType {
+    /**
+     * An original audio track of the video.
+     */
+    ORIGINAL,
+
+    /**
+     * An audio track with the original voices replaced, typically in a different language.
+     *
+     * @see <a href="https://en.wikipedia.org/wiki/Dubbing">
+     * https://en.wikipedia.org/wiki/Dubbing</a>
+     */
+    DUBBED,
+
+    /**
+     * A descriptive audio track.
+     * <p>
+     * A descriptive audio track is an audio track in which descriptions of visual elements of
+     * a video are added to the original audio, with the goal to make a video more accessible to
+     * blind and visually impaired people.
+     * </p>
+     *
+     * @see <a href="https://en.wikipedia.org/wiki/Audio_description">
+     * https://en.wikipedia.org/wiki/Audio_description</a>
+     */
+    DESCRIPTIVE
+}

extractor/src/test/java/org/schabi/newpipe/extractor/services/youtube/YoutubeDashManifestCreatorsTest.java

@@ -8,6 +8,7 @@
 import org.schabi.newpipe.extractor.services.youtube.dashmanifestcreators.YoutubeOtfDashManifestCreator;
 import org.schabi.newpipe.extractor.services.youtube.dashmanifestcreators.YoutubeProgressiveDashManifestCreator;
 import org.schabi.newpipe.extractor.services.youtube.extractors.YoutubeStreamExtractor;
+import org.schabi.newpipe.extractor.stream.AudioTrackType;
 import org.schabi.newpipe.extractor.stream.DeliveryMethod;
 import org.schabi.newpipe.extractor.stream.Stream;
 import org.w3c.dom.Document;
@@ -233,7 +234,27 @@ private void assertAdaptationSetElement(@Nonnull final Document document,
     private void assertRoleElement(@Nonnull final Document document,
                                    @Nonnull final ItagItem itagItem) {
         final Element element = assertGetElement(document, ROLE, ADAPTATION_SET);
-        assertAttrEquals(itagItem.isDescriptiveAudio() ? "alternate" : "main", element, "value");
+
+        final String expect;
+        if (itagItem.getAudioTrackType() == null) {
+            expect = "main";
+        } else {
+            switch (itagItem.getAudioTrackType()) {
+                case ORIGINAL:
+                    expect = "main";
+                    break;
+                case DUBBED:
+                    expect = "dub";
+                    break;
+                case DESCRIPTIVE:
+                    expect = "description";
+                    break;
+                default:
+                    expect = "alternate";
+            }
+        }
+
+        assertAttrEquals(expect, element, "value");
     }
 
     private void assertRepresentationElement(@Nonnull final Document document,