# YouTube Clippy (ytclip)
A fast and efficient YouTube video clip downloader that extracts specific time segments without downloading entire videos.
## Features
- **Stream-based clipping** - Downloads only the specified segment, not the entire video
- **Timestamp support** - Specify exact start and end times
- **Speed adjustment** - Change playback speed (0.5x to 4x)
- **QuickTime compatible** - Outputs H.264/AAC MP4 files
- **Minimal dependencies** - Just needs yt-dlp and ffmpeg
## Installation
### Prerequisites
You need to have `ffmpeg` installed on your system:
**macOS:**
```bash
brew install ffmpeg
```
**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install ffmpeg
```
**Windows:**
Download from [ffmpeg.org](https://ffmpeg.org/download.html) and add to PATH
### Install from PyPI
```bash
pip install youtube-clippy
```
### Install from source
```bash
git clone https://github.com/eden-chan/youtube-clippy.git
cd youtube-clippy
pip install -e .
```
## Usage
### Basic Usage
Download a clip from a YouTube video:
```bash
ytclip "https://youtu.be/VIDEO_ID" START_TIME END_TIME
```
### Examples
Extract clip from 1:30 to 2:45:
```bash
ytclip "https://youtu.be/dQw4w9WgXcQ" 1:30 2:45
```
Extract with custom output filename:
```bash
ytclip "https://youtu.be/dQw4w9WgXcQ" 1:30 2:45 -o my_clip.mp4
```
Extract at 1.5x speed:
```bash
ytclip "https://youtu.be/dQw4w9WgXcQ" 1:30 2:45 --speed 1.5
```
Extract from timestamp in HH:MM:SS format:
```bash
ytclip "https://youtu.be/dQw4w9WgXcQ" 1:23:45 1:24:30
```
### Command Line Options
```
positional arguments:
url YouTube video URL
start Start time (MM:SS or HH:MM:SS)
end End time (MM:SS or HH:MM:SS)
optional arguments:
-h, --help Show help message and exit
-o OUTPUT, --output OUTPUT
Output filename (default: auto-generated)
-s SPEED, --speed SPEED
Playback speed (e.g., 1.5 for 1.5x speed, 0.5 for half speed)
Range: 0.25 to 4.0 (default: 1.0)
-v, --version Show version number
```
## How It Works
Unlike traditional YouTube downloaders that fetch entire videos, `ytclip` uses ffmpeg's seeking capability to stream only the required segment. This means:
- **Faster downloads** - Only downloads what you need
- **Less bandwidth** - Saves data by not downloading unnecessary content
- **Less storage** - No temporary full-video files
The tool:
1. Extracts video metadata using yt-dlp
2. Calculates the exact byte range needed
3. Uses ffmpeg to stream and transcode only that segment
4. Outputs a properly formatted MP4 file
## Output Format
All clips are encoded as:
- **Video**: H.264 (libx264) with yuv420p pixel format
- **Audio**: AAC
- **Container**: MP4 with faststart flag (optimized for streaming)
This ensures compatibility with all modern video players including:
- QuickTime Player
- VLC
- Windows Media Player
- Web browsers
- Mobile devices
## Speed Adjustment
The speed option maintains pitch correction for natural-sounding audio:
- **0.25x - 0.5x**: Slow motion with preserved audio pitch
- **0.5x - 2.0x**: Standard speed adjustment
- **2.0x - 4.0x**: Fast playback with intelligible audio
Note: Extreme speed changes may affect video quality.
## Troubleshooting
### "ffmpeg not found" error
Make sure ffmpeg is installed and in your system PATH:
```bash
ffmpeg -version
```
### "Video unavailable" error
- Check if the video is public and not geo-restricted
- Try updating yt-dlp: `pip install --upgrade yt-dlp`
### QuickTime compatibility issues
The tool automatically encodes to H.264/AAC which should work in QuickTime. If you still have issues, try:
```bash
ytclip "URL" START END -o clip.mp4
```
## Development
### Running from source
```bash
python -m ytclip.cli "URL" START END
```
### Running tests
```bash
python -m pytest tests/
```
## License
MIT License - see LICENSE file for details
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Credits
Built with:
- [yt-dlp](https://github.com/yt-dlp/yt-dlp) - YouTube video extractor
- [FFmpeg](https://ffmpeg.org/) - Video processing
## Links
- **GitHub**: https://github.com/eden-chan/youtube-clippy
- **PyPI**: https://pypi.org/project/youtube-clippy/
- **Issues**: https://github.com/eden-chan/youtube-clippy/issues
## Changelog
### v1.0.0 (2024-01-09)
- Initial release
- Stream-based clip extraction
- Speed adjustment support
- QuickTime compatible output
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/ytclip",
"name": "youtube-clippy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "youtube, video, downloader, clip, timestamp, ffmpeg",
"author": "Your Name",
"author_email": "Your Name <your.email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/87/f6/d1fc7fccdf9e98b5297aab0e6e8117cafa267aba8942c299e145627e94a7/youtube_clippy-1.0.1.tar.gz",
"platform": null,
"description": "# YouTube Clippy (ytclip)\n\nA fast and efficient YouTube video clip downloader that extracts specific time segments without downloading entire videos.\n\n## Features\n\n- **Stream-based clipping** - Downloads only the specified segment, not the entire video\n- **Timestamp support** - Specify exact start and end times\n- **Speed adjustment** - Change playback speed (0.5x to 4x)\n- **QuickTime compatible** - Outputs H.264/AAC MP4 files\n- **Minimal dependencies** - Just needs yt-dlp and ffmpeg\n\n## Installation\n\n### Prerequisites\n\nYou need to have `ffmpeg` installed on your system:\n\n**macOS:**\n```bash\nbrew install ffmpeg\n```\n\n**Ubuntu/Debian:**\n```bash\nsudo apt update\nsudo apt install ffmpeg\n```\n\n**Windows:**\nDownload from [ffmpeg.org](https://ffmpeg.org/download.html) and add to PATH\n\n### Install from PyPI\n\n```bash\npip install youtube-clippy\n```\n\n### Install from source\n\n```bash\ngit clone https://github.com/eden-chan/youtube-clippy.git\ncd youtube-clippy\npip install -e .\n```\n\n## Usage\n\n### Basic Usage\n\nDownload a clip from a YouTube video:\n\n```bash\nytclip \"https://youtu.be/VIDEO_ID\" START_TIME END_TIME\n```\n\n### Examples\n\nExtract clip from 1:30 to 2:45:\n```bash\nytclip \"https://youtu.be/dQw4w9WgXcQ\" 1:30 2:45\n```\n\nExtract with custom output filename:\n```bash\nytclip \"https://youtu.be/dQw4w9WgXcQ\" 1:30 2:45 -o my_clip.mp4\n```\n\nExtract at 1.5x speed:\n```bash\nytclip \"https://youtu.be/dQw4w9WgXcQ\" 1:30 2:45 --speed 1.5\n```\n\nExtract from timestamp in HH:MM:SS format:\n```bash\nytclip \"https://youtu.be/dQw4w9WgXcQ\" 1:23:45 1:24:30\n```\n\n### Command Line Options\n\n```\npositional arguments:\n url YouTube video URL\n start Start time (MM:SS or HH:MM:SS)\n end End time (MM:SS or HH:MM:SS)\n\noptional arguments:\n -h, --help Show help message and exit\n -o OUTPUT, --output OUTPUT\n Output filename (default: auto-generated)\n -s SPEED, --speed SPEED\n Playback speed (e.g., 1.5 for 1.5x speed, 0.5 for half speed)\n Range: 0.25 to 4.0 (default: 1.0)\n -v, --version Show version number\n```\n\n## How It Works\n\nUnlike traditional YouTube downloaders that fetch entire videos, `ytclip` uses ffmpeg's seeking capability to stream only the required segment. This means:\n\n- **Faster downloads** - Only downloads what you need\n- **Less bandwidth** - Saves data by not downloading unnecessary content\n- **Less storage** - No temporary full-video files\n\nThe tool:\n1. Extracts video metadata using yt-dlp\n2. Calculates the exact byte range needed\n3. Uses ffmpeg to stream and transcode only that segment\n4. Outputs a properly formatted MP4 file\n\n## Output Format\n\nAll clips are encoded as:\n- **Video**: H.264 (libx264) with yuv420p pixel format\n- **Audio**: AAC \n- **Container**: MP4 with faststart flag (optimized for streaming)\n\nThis ensures compatibility with all modern video players including:\n- QuickTime Player\n- VLC\n- Windows Media Player\n- Web browsers\n- Mobile devices\n\n## Speed Adjustment\n\nThe speed option maintains pitch correction for natural-sounding audio:\n- **0.25x - 0.5x**: Slow motion with preserved audio pitch\n- **0.5x - 2.0x**: Standard speed adjustment\n- **2.0x - 4.0x**: Fast playback with intelligible audio\n\nNote: Extreme speed changes may affect video quality.\n\n## Troubleshooting\n\n### \"ffmpeg not found\" error\nMake sure ffmpeg is installed and in your system PATH:\n```bash\nffmpeg -version\n```\n\n### \"Video unavailable\" error\n- Check if the video is public and not geo-restricted\n- Try updating yt-dlp: `pip install --upgrade yt-dlp`\n\n### QuickTime compatibility issues\nThe tool automatically encodes to H.264/AAC which should work in QuickTime. If you still have issues, try:\n```bash\nytclip \"URL\" START END -o clip.mp4\n```\n\n## Development\n\n### Running from source\n```bash\npython -m ytclip.cli \"URL\" START END\n```\n\n### Running tests\n```bash\npython -m pytest tests/\n```\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Credits\n\nBuilt with:\n- [yt-dlp](https://github.com/yt-dlp/yt-dlp) - YouTube video extractor\n- [FFmpeg](https://ffmpeg.org/) - Video processing\n\n## Links\n\n- **GitHub**: https://github.com/eden-chan/youtube-clippy\n- **PyPI**: https://pypi.org/project/youtube-clippy/\n- **Issues**: https://github.com/eden-chan/youtube-clippy/issues\n\n## Changelog\n\n### v1.0.0 (2024-01-09)\n- Initial release\n- Stream-based clip extraction\n- Speed adjustment support\n- QuickTime compatible output\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A fast YouTube video clip downloader with timestamp support",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/yourusername/ytclip",
"Issues": "https://github.com/yourusername/ytclip/issues"
},
"split_keywords": [
"youtube",
" video",
" downloader",
" clip",
" timestamp",
" ffmpeg"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b72397af48bd42bf639ccc33691a67b04554202e43ac8b1991dff0e37a349e90",
"md5": "bf37dfbe50151f1efa3d549b2d2b2b79",
"sha256": "52968195f335dc537eb7560b426547862f320c611bb40799243bb707f20372e3"
},
"downloads": -1,
"filename": "youtube_clippy-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bf37dfbe50151f1efa3d549b2d2b2b79",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7186,
"upload_time": "2025-09-04T13:23:18",
"upload_time_iso_8601": "2025-09-04T13:23:18.818599Z",
"url": "https://files.pythonhosted.org/packages/b7/23/97af48bd42bf639ccc33691a67b04554202e43ac8b1991dff0e37a349e90/youtube_clippy-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "87f6d1fc7fccdf9e98b5297aab0e6e8117cafa267aba8942c299e145627e94a7",
"md5": "b5b0d7a70d2ef88f3bebe275f37d8a50",
"sha256": "2639ed21e071bc27b4d4ecab9c8ad988a5c4d688232f74767d9ce3f0af688dfc"
},
"downloads": -1,
"filename": "youtube_clippy-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "b5b0d7a70d2ef88f3bebe275f37d8a50",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 6854,
"upload_time": "2025-09-04T13:23:19",
"upload_time_iso_8601": "2025-09-04T13:23:19.637596Z",
"url": "https://files.pythonhosted.org/packages/87/f6/d1fc7fccdf9e98b5297aab0e6e8117cafa267aba8942c299e145627e94a7/youtube_clippy-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-04 13:23:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "ytclip",
"github_not_found": true,
"lcname": "youtube-clippy"
}
JSON
