Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@Hexer10
Hexer10 committed Oct 25, 2024
1 parent 44b2ef7 commit 1d5c476
Showing 1 changed file with 77 additions and 48 deletions.
125 changes: 77 additions & 48 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,35 +11,28 @@ It used to build [Youtube Downloader Flutter](https://github.com/Hexer10/youtube

YoutubeExplode is a library that provides an interface to query metadata of YouTube videos, playlists and channels, as well as to resolve and download video streams and closed caption tracks. Behind a layer of abstraction, the library parses raw page content and uses reverse-engineered AJAX requests to retrieve information. As it doesn't use the official API, there's also no need for an API key and there are no usage quotas.

## Features from YoutubeExplode
## Features

- Retrieve metadata on videos, playlists, channels, streams, and closed captions
- Execute search queries and get resulting videos.
- Get or download video streams.
- Get closed captions.
- Get video comments.
- All model extend `Equatable` to easily perform equality checks

## Differences from YoutubeExplode

- The entry point is `YoutubeExplode`, not `YoutubeClient`.
- Download closed captions as `srt` is not supported yet.
- Search queries can be fetched from the search page as well (thus fetch Videos, Channels and Playlists).
- More APIs implemented.

## Usage
- [Install](#install)
- [Downloading a video stream](#downloading-a-video-stream)
- [Working with playlists](#working-with-playlists)
- [Extracting closed captions](#extracting-closed-captions)
- [Getting comments](#getting-comments)
- [Getting comments](#get-comments)
- [Cleanup](#cleanup)
- [Before reporting an issue](#troubleshooting)

### Install

Add the dependency to the pubspec.yaml (Check for the latest version)
```yaml
youtube_explode_dart: ^1.10.4
youtube_explode_dart: ^2.3.4
```
Import the library
Expand All @@ -59,25 +52,13 @@ var author = video.author; // "Jim Browning"
var duration = video.duration; // Instance of Duration - 0:19:48.00000
```

#### Get a list of related videos
```dart
var video = yt.videos.get('https://youtube.com/watch?v=Dpp1sIL1m5Q');
var relatedVideos = await yt.videos.getRelatedVideos(video); // video must be a Video instance.
print(relatedVideos); //prints the list of related videos
// to get the next page of related videos
relatedVideos = await relatedVideos.nextPage();
```

If no related video is found `getRelatedVideos` or `nextPage` will return null.

### Downloading a video stream
Every YouTube video has a number of streams available. These streams may have different containers, video quality, bitrate, etc.

On top of that, depending on the content of the stream, the streams are further divided into 3 categories:
- Muxed streams -- contain both video and audio
- Muxed streams -- contain both video and audio (available only in 360p)
- Audio-only streams -- contain only audio
-- Video-only streams -- contain only video
- Video-only streams -- contain only video

You can request the stream manifest to get available streams for a particular video:

Expand All @@ -86,42 +67,51 @@ You can request the stream manifest to get available streams for a particular vi
var yt = YoutubeExplode();
var manifest = yt.videos.streams.getManifest('Dpp1sIL1m5Q');
print(manifest); // Prints the list of streams available for the video.
// If you want to specify which youtube clients to use to get the manifest you can do so:
var manifest = yt.videos.streams.getManifest(videoId, ytClients: [
YoutubeApiClient.safari,
YoutubeApiClient.androidVr
]); // The streams provided by both clients will be merged.
```

Once you get the manifest, you can filter through the streams and choose the one you're interested in downloading:

```dart
// Get highest quality muxed stream
var streamInfo = streamManifest.muxed.withHigestVideoQuality();
// highest bitrate audio-only stream
var streamInfo = streamManifest.audioOnly.withHigestBitrate();
// ...or highest bitrate audio-only stream
var streamInfo = streamManifest.audioOnly.withHigestBitrate()
// MP4 video-only stream
var streamInfo.videoOnly.where((e) => e.container == Container);
// ...or highest quality MP4 video-only stream
var streamInfo.videoOnly.where((e) => e.container == Container)
// Muxed (audio + video) stream with the highest video quality. NOTE: Don't rely on this, muxed streams are limited to 360p30.
var streamInfo = streamManifest.muxed.withHigestVideoQuality();
// HLS (m3u8) streams are also supported
var streamInfo = streamManifest.hls;
```

Finally, you can get the actual `Stream` object represented by the metadata:

```dart
if (streamInfo != null) {
// Get the actual stream
var stream = yt.video.streams.get(streamInfo);
// Open a file for writing.
var file = File(filePath);
var fileStream = file.openWrite();
// Get the actual byte stream
var stream = yt.video.streams.get(streamInfo);
// Pipe all the content of the stream into the file.
await stream.pipe(fileStream);
// Open a file for writing.
var file = File(filePath);
var fileStream = file.openWrite();
// Close the file.
await fileStream.flush();
await fileStream.close();
}
// Pipe all the content of the stream into the file.
await stream.pipe(fileStream);
// Close the file.
await fileStream.flush();
await fileStream.close();
```

While it may be tempting to just always use muxed streams, it's important to note that they are limited in quality. Muxed streams don't go beyond 720p30.
While it may be tempting to just always use muxed streams, it's important to note that they are limited in quality. **Muxed streams don't go beyond 360p30.**

If you want to download the video in maximum quality, you need to download the audio-only and video-only streams separately and then mux them together on your own. There are tools like FFmpeg that let you do that.

Expand Down Expand Up @@ -168,7 +158,20 @@ Similarly, to streams, you can extract closed captions by getting the manifest a
}
```

### Getting comments
#### Get a list of related videos
```dart
var video = yt.videos.get('https://youtube.com/watch?v=Dpp1sIL1m5Q');
var relatedVideos = await yt.videos.getRelatedVideos(video); // video must be a Video instance.
print(relatedVideos); //prints the list of related videos
// to get the next page of related videos
relatedVideos = await relatedVideos.nextPage();
```

If no related video is found `getRelatedVideos` or `nextPage` will return null.


### Get comments
You can easily get the video comments of a given video, the return value of `comments.getComments(video)` is a list-like object which behaves exactly like a `List` but has an additional method `nextPage()` which is used in order to get the next comments, it returns null when there are no comments to be fetched anymore.

```dart
Expand All @@ -186,6 +189,28 @@ You need to close `YoutubeExplode`'s http client, when done otherwise this could
yt.close();
```

### Troubleshooting
If you encounter any issues, please check that it has not been reported already in the [issues section](Issue).

When reporting a new issue, make sure to follow the issue template and report the logs after having enabled the logging:
```dart
import 'package:logging/logging.dart';
...
// Before any YoutubeExplode code
Logger.root.level = Level.FINER;
Logger.root.onRecord.listen((e) {
print(e);
if (e.error != null) {
print(e.error);
print(e.stackTrace);
}
});
```

To the very minimum the video id causing the issue (if applicable) and the code snippet that is causing the issue must be provided.

### Examples:

More examples available on [GitHub][Examples].
Expand All @@ -198,9 +223,10 @@ You can find how most APIs can be used in the files inside the test/ folder.

### Credits

- [Tyrrrz] for creating [YoutubeExplode] for C#
- [Hexer10] (Me) who ported the library over to Dart.
- [Tyrrrz] for creating [YoutubeExplode] in C#
- [Hexer10] (me) who ported the library over to Dart.
- [EnsembleUI] for the jsparser project.
- [yt-dlp] for documentation and reverse engineering about the YouTube apis.
- All the [Contributors] of this repository.

[YoutubeExplode]: https://github.com/Tyrrrz/YoutubeExplode/
Expand All @@ -210,3 +236,6 @@ You can find how most APIs can be used in the files inside the test/ folder.
[Hexer10]: https://github.com/Hexer10/
[Contributors]: https://github.com/Hexer10/youtube_explode_dart/graphs/contributors
[EnsembleUI]: https://github.com/EnsembleUI
[Issue]: https://github.com/Hexer10/youtube_explode_dart/issues
[yt-dlp]: https://github.com/yt-dlp/yt-dlp

0 comments on commit 1d5c476

Please sign in to comment.