# 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.
## 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. If `true`, the videos will be converted to audio.
### 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",
"convert_to_audio": false
}
]
}
```
## 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.
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/4e/8b/ed04b9dccecff795e10d1e92417b95f62fe8ccc5634a3e23405fa25609a3/sync_yt-1.0.1.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\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. If `true`, the videos will be converted to audio.\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 \"convert_to_audio\": false\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",
"bugtrack_url": null,
"license": null,
"summary": "CLI tool to mirror YouTube playlists into local directories",
"version": "1.0.1",
"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": "5bcc8b4bdb9a84acd8b2775a608574ca738b8700d7520cdd9f448f8f869cffec",
"md5": "45e583ef1135d5d762aaaba508c89964",
"sha256": "2a685af6f871d948884e42142fdfbda6564dca8fc78e8514021d3c76c73d9a92"
},
"downloads": -1,
"filename": "sync_yt-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "45e583ef1135d5d762aaaba508c89964",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 6701,
"upload_time": "2025-09-05T19:29:41",
"upload_time_iso_8601": "2025-09-05T19:29:41.399425Z",
"url": "https://files.pythonhosted.org/packages/5b/cc/8b4bdb9a84acd8b2775a608574ca738b8700d7520cdd9f448f8f869cffec/sync_yt-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4e8bed04b9dccecff795e10d1e92417b95f62fe8ccc5634a3e23405fa25609a3",
"md5": "7b0a2a66a4bc287d0c0895c25a90ac95",
"sha256": "b4fde4b5613f12ef3027dfbaeab90d92a763ebe4018fb5cd0b32b0c06474c063"
},
"downloads": -1,
"filename": "sync_yt-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "7b0a2a66a4bc287d0c0895c25a90ac95",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 6442,
"upload_time": "2025-09-05T19:29:43",
"upload_time_iso_8601": "2025-09-05T19:29:43.300482Z",
"url": "https://files.pythonhosted.org/packages/4e/8b/ed04b9dccecff795e10d1e92417b95f62fe8ccc5634a3e23405fa25609a3/sync_yt-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-05 19:29:43",
"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
