Metadata-Version: 2.4
Name: youtube-playlist-exporter
Version: 0.3.0
Summary: A CLI for exporting YouTube playlists' data to local files
Author-email: Dean Gurvitz <deansg@gmail.com>
License-Expression: Apache-2.0
Project-URL: homepage, https://github.com/deansg/youtube-playlist-exporter
Keywords: CLI,YouTube
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp==3.11.16
Requires-Dist: dataclasses-json>=0.6.7
Requires-Dist: google-auth-oauthlib>=1.2.2
Requires-Dist: typer>=0.15.2
Dynamic: license-file

# YouTube Playlist Exporter

Tired of videos disappearing from your YouTube playlists, without leaving you the option to know what was there before?

Fear not! For this CLI will have you covered

![alt text](memes/2.jpg)

This CLI allows exporting data about videos in your playlist to local files, that can be used as a backup in case
videos from the playlist become private/get deleted.

If the CLI runs in a directory which contains output files from a previous run (with the same parameters), it will
automatically detect differences in the specified playlist, and export them to files as well.

## Installation

This CLI requires Python 3.10+ to run. It is published to [PyPI](https://pypi.org/project/youtube-playlist-exporter/)
and can be installed with pip using:

`pip install youtube-playlist-exporter`

## Usage

1. Get a YouTube API Key. To do so, you can follow the instructions
   in [this guide](https://elfsight.com/help/how-to-get-youtube-api-key/) (**this only needs to be done once for all
   future CLI runs**)
2. If your playlist is private, see the next section for additional, more advanced setup that you need to perform after
   creating the API Key
3. Retrieve the YouTube ID of the playlist you want to create a backup for. This can be done in several ways. One of
   them is by navigating to the playlist's main YouTube page, and copying the text after "...list=" in the URL
4. If you didn't do so already, install the CLI (see [installation](#installation))
5. Run the CLI using either the `ype` or `youtube-playlist-export` commands (full details on the CLI syntax are provided
   by running with the `--help` flag)
6. Several `.csv` files (tables which can be opened with Excel/imported to Google Sheets etc.) will be generated by the
   script in the output directory (`<PLAYLIST_NAME>` will be replaced with the name provided as an argument to the CLI):
    * `YouTube-<PLAYLIST_NAME>-items.csv`: contains the current details of all the videos in the playlist
    * `YouTube-<PLAYLIST_NAME>-items-backup.csv`: if an `...items.csv` file existed in the output directory before
      running the script, this file will be a backup for it (in case something went wrong with running the script etc.)
    * `YouTube-<PLAYLIST_NAME>-diff.csv`: if an `...items.csv` file existed in the output directory before
      running the script, this file will contain information about videos whose title changed. This can help detect
      videos that now appear as private or deleted, or any other unexpected changes
    * `YouTube-<PLAYLIST_NAME>-diff-backup.csv`: if a `...diff.csv` file existed in the output directory
      before running the script, this file will contain a backup for it
    * `YouTube-<PLAYLIST_NAME>-missing-videos.csv`: if an `...items.csv` file existed in the output directory before
      running the script, this file will contain information about videos that existed before and now don't exist in
      the playlist anymore. Note: sometimes deleted videos will still appear but just with a title change of "deleted
      video", and sometimes they will go missing completely and appear in this file
    * `YouTube-<PLAYLIST_NAME>-missing-videos-backup.csv`: if a `...missing-videos.csv` file existed in the output
      directory before running the script, this file will contain a backup for it

### [Advanced] Additional setup for exporting data from private playlists

If your playlist is private, extra setup is required for the script to be able to export data from it. In addition,
running the CLI to retrieve data from private playlists will open a browser window and require you to manually
authenticate. The necessary extra steps are:

1. Go to https://console.cloud.google.com/apis/dashboard (where)
2. Click on "OAuth consent screen" on the sidebar to the left, and then go to "Clients"
3. Create a new client for OAuth2 access with the type field set to "Desktop"
4. Navigate to the created client, and click "Download JSON"
5. When calling the CLI, you will need to specify the `--private-playlist` argument, and also provide the path of the
   downloaded file using the `--secret-file` argument
6. In the audience section, add your user as a test user
7. Continue setup from previous section

## FAQ

### How do I raise issues with the project?

You can either open issues on the GitHub project or email deansg@gmail.com

### What do I do if I want to recover videos that are already private/deleted before I started using the tool?

In that case you need to retrieve the URLs of the problematic videos, and can then try to use either Google them to see
if their titles appear in the search results, or use Wayback Machine.

### Is there a way to use the tool without having Python installed?

Currently, the tool can be run / installed only on machines that have Python. If you have ideas for other ways to
distribute it that may be beneficial to others please let me know!
