# sync-yt
**sync-yt** is a command-line tool that synchronizes YouTube playlists to local directories on your system.
It uses yt-dlp for downloading videos and a JSON based configuration file to define playlists and other options.
## Features
+ Declarative config.json to specify playlists and other configurable options.
+ Option to save playlists in audio-only format, useful for music playlists.
+ Can sync private YouTube playlists by specifying the logged-in browser.
+ Automatically skips repeated video entries.
+ Detects videos which become unavailable.
+ Add metadata and thumbnail to audio files
## Requirements
+ Python 3.10+
+ yt-dlp
+ FFmpeg (Optional but highly recommended)
## Installation
+ ### Windows
+ #### Install FFmpeg
Follow this [guide](https://www.geeksforgeeks.org/installation-guide/how-to-install-ffmpeg-on-windows/) to properly install FFmpeg on Windows.
+ #### Install `sync-yt`
```
$ pip install sync-yt
```
+ ### Arch Linux
`sync-yt` is available on [AUR](https://aur.archlinux.org/packages/sync-yt). Use your favourite AUR helper.
```
$ yay -S sync-yt
```
+ ### Other Linux Distributions / macOS
Since `sync-yt` requires the latest version of `yt-dlp`, which may not be available in your OS’s official repositories,
using `pipx` is recommended.
+ #### Install `pipx`
##### Debain and derivatives (Ubuntu, Mint, Zorin etc..)
```
$ sudo apt install pipx
```
##### macOS
```
$ brew install pipx
```
+ #### Install `sync-yt`
```
$ pipx ensurepath
$ pipx install sync-yt
```
## Configuration
Configuration file is first searched at `~/.config/sync-yt/config.json` on POSIX compliant systems or at\
`C:\Users\<User>\AppData\Local\sync-yt\config.json` on Windows.
## config.json
### `sync_dir`
- **Type**: `string`
- **Description**: Specifies the local directory where YouTube playlist folders will be synced. This path can be relative to the user's home directory (using `~`) or an absolute path.
- **Examples**: `"~/Music" , "D:\YouTube"`
### `cookies_from_browser`
- **Type**: `string`
- **Description**: Specifies the browser from which cookies should be extracted. This is required for downloading private playlists that are accessible only when signed into a Google account. Supported browsers include `firefox`, `chrome`, `edge`, etc. You can choose to leave this option blank if you're not downloading private playlists.
- **Examples**: `"firefox", "chrome", "brave", "edge", "vivaldi"`
### `playlists`
- **Type**: `array`
- **Description**: An array of playlist objects, where each object represents a YouTube playlist to be synced. Each object in the array has the following properties:
- **`name`**
- **Type**: `string`
- **Description**: A descriptive name to refer the playlist. This is the name of folder created in `sync_dir` where corresponding playlist is synced.
- **`url`**
- **Type**: `string`
- **Description**: The URL of the YouTube playlist.
- **Example**: `"https://www.youtube.com/playlist?list=PLSdoVPM5WnndSQEXRz704yQkKwx76GvPV"`
- **`convert_to_audio`**
- **Type**: `boolean`
- **Description**: Indicates whether the videos in the playlist should be converted to audio files. Set it to `true` if you want an audio file. If the entry is omitted, it will be set to `false` by default.
- **`format`**
- **Type**: `string`
- **Description**: Indicate the audio or video codec you want. If the entry is omitted, it will be set to `best` by default.
- Supported video formats: `avi, flv, mkv, mov, mp4, webm`
- Supported audio formats (requires `convert_to_audio` set to `true`): `aac, alac, flac, m4a, mp3, opus, vorbis, wav`
- **Example**: `"mp3"` or `"mkv"`
### Example Configuration
Below is a sample `config.json` file demonstrating the use of the configuration options:
```json
{
"sync_dir": "~/Music",
"cookies_from_browser": "firefox",
"playlists": [
{
"name": "Daft Punk - Discovery",
"url": "https://www.youtube.com/playlist?list=PLSdoVPM5WnndSQEXRz704yQkKwx76GvPV",
"convert_to_audio": true
},
{
"name": "Minuscule Compilation",
"url": "https://www.youtube.com/playlist?list=PL7eLsxQrsg-4DNH682TNzgSlCXEeJ3IsX",
"format": "mp4"
}
]
}
```
## Usage
```
$ sync-yt
```
## Notes
+ Manual intervention is needed when a video becomes unavailable. Remove it from upstream youtube playlist to get rid of error/warning.
Upon removal from upstream playlist it will be removed locally as well on next sync. So backup before syncing if needed.
+ Two different playlist can share same `name` attribute to sync both playlists in a single folder.
+ You can skip installation of FFmpeg but it is highly recommended especially if you are using `convert_to_audio` option.
+ metadata and thumbnail will be add to audio files only if the codec is compatible (like .mp3 or .flac)
Raw data
{
"_id": null,
"home_page": null,
"name": "sync-yt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "yt-dlp, youtube, playlist, sync, downloader, music, videos, cli",
"author": null,
"author_email": "Siddhesh Dharme <siddheshdharme18@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b7/c4/f67d73bdc9842badb89b59f029166da5cee9162f8e908612414ed6ed8815/sync_yt-1.1.0.tar.gz",
"platform": null,
"description": "# sync-yt\n**sync-yt** is a command-line tool that synchronizes YouTube playlists to local directories on your system.\nIt uses yt-dlp for downloading videos and a JSON based configuration file to define playlists and other options.\n\n## Features\n+ Declarative config.json to specify playlists and other configurable options.\n+ Option to save playlists in audio-only format, useful for music playlists.\n+ Can sync private YouTube playlists by specifying the logged-in browser.\n+ Automatically skips repeated video entries.\n+ Detects videos which become unavailable.\n+ Add metadata and thumbnail to audio files\n\n## Requirements\n+ Python 3.10+\n+ yt-dlp\n+ FFmpeg (Optional but highly recommended)\n\n## Installation\n\n+ ### Windows\n + #### Install FFmpeg\n Follow this [guide](https://www.geeksforgeeks.org/installation-guide/how-to-install-ffmpeg-on-windows/) to properly install FFmpeg on Windows.\n + #### Install `sync-yt`\n ```\n $ pip install sync-yt\n ```\n\n+ ### Arch Linux\n `sync-yt` is available on [AUR](https://aur.archlinux.org/packages/sync-yt). Use your favourite AUR helper.\n ```\n $ yay -S sync-yt\n ```\n\n+ ### Other Linux Distributions / macOS\n Since `sync-yt` requires the latest version of `yt-dlp`, which may not be available in your OS\u2019s official repositories,\n using `pipx` is recommended.\n + #### Install `pipx`\n ##### Debain and derivatives (Ubuntu, Mint, Zorin etc..)\n ```\n $ sudo apt install pipx\n ``` \n ##### macOS\n ```\n $ brew install pipx\n ```\n + #### Install `sync-yt`\n ```\n $ pipx ensurepath\n $ pipx install sync-yt\n ```\n\n## Configuration\n\nConfiguration file is first searched at `~/.config/sync-yt/config.json` on POSIX compliant systems or at\\\n`C:\\Users\\<User>\\AppData\\Local\\sync-yt\\config.json` on Windows.\n\n## config.json\n\n### `sync_dir`\n- **Type**: `string`\n- **Description**: Specifies the local directory where YouTube playlist folders will be synced. This path can be relative to the user's home directory (using `~`) or an absolute path.\n- **Examples**: `\"~/Music\" , \"D:\\YouTube\"`\n\n### `cookies_from_browser`\n- **Type**: `string`\n- **Description**: Specifies the browser from which cookies should be extracted. This is required for downloading private playlists that are accessible only when signed into a Google account. Supported browsers include `firefox`, `chrome`, `edge`, etc. You can choose to leave this option blank if you're not downloading private playlists.\n- **Examples**: `\"firefox\", \"chrome\", \"brave\", \"edge\", \"vivaldi\"`\n\n### `playlists`\n- **Type**: `array`\n- **Description**: An array of playlist objects, where each object represents a YouTube playlist to be synced. Each object in the array has the following properties:\n\n - **`name`**\n - **Type**: `string`\n - **Description**: A descriptive name to refer the playlist. This is the name of folder created in `sync_dir` where corresponding playlist is synced.\n\n - **`url`**\n - **Type**: `string`\n - **Description**: The URL of the YouTube playlist.\n - **Example**: `\"https://www.youtube.com/playlist?list=PLSdoVPM5WnndSQEXRz704yQkKwx76GvPV\"`\n\n - **`convert_to_audio`**\n - **Type**: `boolean`\n - **Description**: Indicates whether the videos in the playlist should be converted to audio files. Set it to `true` if you want an audio file. If the entry is omitted, it will be set to `false` by default.\n\n - **`format`**\n\t - **Type**: `string`\n - **Description**: Indicate the audio or video codec you want. If the entry is omitted, it will be set to `best` by default.\n - Supported video formats: `avi, flv, mkv, mov, mp4, webm`\n - Supported audio formats (requires `convert_to_audio` set to `true`): `aac, alac, flac, m4a, mp3, opus, vorbis, wav`\n - **Example**: `\"mp3\"` or `\"mkv\"`\n\n\n### Example Configuration\n\nBelow is a sample `config.json` file demonstrating the use of the configuration options:\n\n```json\n{\n \"sync_dir\": \"~/Music\",\n \"cookies_from_browser\": \"firefox\",\n \"playlists\": [\n {\n \"name\": \"Daft Punk - Discovery\",\n \"url\": \"https://www.youtube.com/playlist?list=PLSdoVPM5WnndSQEXRz704yQkKwx76GvPV\",\n \"convert_to_audio\": true\n },\n {\n \"name\": \"Minuscule Compilation\",\n \"url\": \"https://www.youtube.com/playlist?list=PL7eLsxQrsg-4DNH682TNzgSlCXEeJ3IsX\",\n \"format\": \"mp4\"\n }\n ]\n}\n```\n\n## Usage\n```\n$ sync-yt\n```\n\n\n## Notes\n\n+ Manual intervention is needed when a video becomes unavailable. Remove it from upstream youtube playlist to get rid of error/warning.\nUpon removal from upstream playlist it will be removed locally as well on next sync. So backup before syncing if needed.\n \n+ Two different playlist can share same `name` attribute to sync both playlists in a single folder.\n\n+ You can skip installation of FFmpeg but it is highly recommended especially if you are using `convert_to_audio` option.\n\n+ metadata and thumbnail will be add to audio files only if the codec is compatible (like .mp3 or .flac)\n",
"bugtrack_url": null,
"license": null,
"summary": "CLI tool to mirror YouTube playlists into local directories",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://pypi.org/project/sync-yt/",
"Issues": "https://github.com/sidtronics/sync-yt/issues",
"Repository": "https://github.com/sidtronics/sync-yt"
},
"split_keywords": [
"yt-dlp",
" youtube",
" playlist",
" sync",
" downloader",
" music",
" videos",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "79ff5257bab6a5da6eee4750bc20c094af05b82ab146ecbf33c7c62b02a0efc7",
"md5": "166b4304164539fef9f08a3292856fe9",
"sha256": "a00c9f7aee31527fc1ab52bb2f02e19b4e4d6e7972cba6623ec9e57265ff9310"
},
"downloads": -1,
"filename": "sync_yt-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "166b4304164539fef9f08a3292856fe9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 7372,
"upload_time": "2025-10-19T17:27:30",
"upload_time_iso_8601": "2025-10-19T17:27:30.022809Z",
"url": "https://files.pythonhosted.org/packages/79/ff/5257bab6a5da6eee4750bc20c094af05b82ab146ecbf33c7c62b02a0efc7/sync_yt-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b7c4f67d73bdc9842badb89b59f029166da5cee9162f8e908612414ed6ed8815",
"md5": "a805f08f7007a7a026357cb476c4a865",
"sha256": "3fc7691d1d2054827e623a84dcede1840707e6240ac8f92112dd37b6d3d0d3d1"
},
"downloads": -1,
"filename": "sync_yt-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "a805f08f7007a7a026357cb476c4a865",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 7115,
"upload_time": "2025-10-19T17:27:31",
"upload_time_iso_8601": "2025-10-19T17:27:31.373877Z",
"url": "https://files.pythonhosted.org/packages/b7/c4/f67d73bdc9842badb89b59f029166da5cee9162f8e908612414ed6ed8815/sync_yt-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-19 17:27:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sidtronics",
"github_project": "sync-yt",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sync-yt"
}
JSON
