ytnb-embed

A lightweight, privacy-focused Python package for embedding YouTube videos in Jupyter Notebooks

Installation • Quick Start • Documentation • Contributing

---

Overview

ytnb-embed provides a simple and elegant way to embed YouTube videos directly in Jupyter Notebooks. Built with privacy and simplicity in mind, it uses YouTube's privacy-enhanced mode (youtube-nocookie.com) to protect user privacy while maintaining full video functionality.

Perfect for data scientists, educators, and researchers who want to enrich their notebooks with video content without compromising on privacy or simplicity.

✨ Features

• 🎥 One-line embedding - Embed any YouTube video with a single function call
• 🔒 Privacy-first - Uses youtube-nocookie.com for enhanced privacy protection
• 📐 Fully customizable - Adjust video player dimensions to fit your needs
• 🛡️ Smart URL parsing - Handles all YouTube URL formats automatically
• 📝 Built-in logging - Comprehensive logging for debugging and monitoring
• ✅ Type hints - Full type annotation support for better IDE integration
• 🧪 Well tested - Includes unit and integration tests
• 🚀 Lightweight - Minimal dependencies, maximum performance

Installation

Install ytnb-embed using pip:

pip install ytnb-embed

Requirements

• Python 3.10+
• Jupyter Notebook or JupyterLab

Quick Start

from ytnb_embed import embed_yt

# Embed a YouTube video with default dimensions (780x440)
embed_yt("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

# Customize the video player size
embed_yt("https://www.youtube.com/watch?v=dQw4w9WgXcQ", width=640, height=360)

That's it! The video will be embedded directly in your Jupyter Notebook cell output.

Usage

Supported URL Formats

ytnb-embed intelligently parses all standard YouTube URL formats:

from ytnb_embed import embed_yt

# Standard watch URL
embed_yt("https://www.youtube.com/watch?v=VIDEO_ID")

# Short URL
embed_yt("https://youtu.be/VIDEO_ID")

# Embed URL
embed_yt("https://www.youtube.com/embed/VIDEO_ID")

# Direct video URL
embed_yt("https://www.youtube.com/v/VIDEO_ID")

# URLs with timestamps and other parameters
embed_yt("https://www.youtube.com/watch?v=VIDEO_ID&t=30s")

Custom Player Dimensions

Tailor the video player size to your notebook layout:

# Large player for presentations
embed_yt("https://www.youtube.com/watch?v=VIDEO_ID", width=1024, height=576)

# Standard 16:9 aspect ratio
embed_yt("https://www.youtube.com/watch?v=VIDEO_ID", width=854, height=480)

# Compact player for documentation
embed_yt("https://www.youtube.com/watch?v=VIDEO_ID", width=560, height=315)

Working Example

Here's a complete example demonstrating common use cases:

from ytnb_embed import embed_yt

# Educational content
print("📚 Python Tutorial:")
embed_yt("https://www.youtube.com/watch?v=_uQrJ0TkZlc", width=800, height=450)

# Conference talks
print("\n🎤 Tech Talk:")
embed_yt("https://youtu.be/cKPlPJyQrt4", width=900, height=506)

# Quick demos
print("\n⚡ Quick Demo:")
embed_yt("https://www.youtube.com/watch?v=VIDEO_ID", width=640, height=360)

🔧 API Reference

embed_yt(url, width=780, height=440)

Embeds a YouTube video in a Jupyter Notebook using an iframe.

Parameters

Parameter	Type	Default	Description
url	str	required	YouTube video URL in any standard format
width	int	780	Width of the video player in pixels
height	int	440	Height of the video player in pixels

Returns

• str: Returns "success" when the video is successfully embedded

Raises

• InvalidURLException: Raised when the provided URL is not a valid YouTube URL
• Exception: Raised for other unexpected errors during embedding

Example

result = embed_yt("https://www.youtube.com/watch?v=VIDEO_ID", width=800, height=450)
# result == "success"

🔒 Privacy & Security

Privacy-Enhanced Mode

ytnb-embed uses YouTube's privacy-enhanced mode by default. Videos are embedded from youtube-nocookie.com, which provides:

• Reduced tracking - YouTube doesn't store information about visitors unless they play the video
• No third-party cookies - Cookies are only set when the user interacts with the video
• Same functionality - All standard YouTube features remain available

Security Features

• URL validation - Regex-based validation prevents injection attacks
• Sandboxed iframe - Videos load in isolated iframe contexts
• Strict referrer policy - strict-origin-when-cross-origin prevents data leakage

Contributing

Contributions are welcome and greatly appreciated! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Make your changes
4. Add tests for new functionality
5. Commit your changes (git commit -m 'Add some AmazingFeature')
6. Push to the branch (git push origin feature/AmazingFeature)
7. Open a Pull Request

Contribution Guidelines

• Write clear, descriptive commit messages
• Add tests for any new features or bug fixes
• Update documentation as needed
• Follow the existing code style (PEP 8)
• Ensure all tests pass before submitting PR

📝 License

This project is licensed under the MIT License - see the LICENSE file for full details.

👤 Author

• GitHub: @aatansen
• Email: aatansen@gmail.com
• PyPI: ytnb-embed

🙏 Acknowledgments

• Built for the Jupyter Notebook community
• Inspired by the need for simple, privacy-focused video embedding
• Thanks to all contributors who help improve this package

📮 Support

If you encounter any issues or have questions:

• 🐛 Bug reports: GitHub Issues
• 💡 Feature requests: GitHub Issues
• 📧 Email: aatansen@gmail.com

📊 Project Stats

Made with ❤️ for the Jupyter community

If you find this package helpful, please consider giving it a ⭐ on GitHub!