ytnoti

Easy-to-use Python library for receiving real-time YouTube push notifications for video uploads, edits, deletions, and live streams.

Documentation  •  Quickstart  •  Examples  •  Changelog  •  Discord

ytnoti is designed to help you receive YouTube push notifications in real-time for video upload, edit, delete, and live stream easily and efficiently.

✨ Features

• Real-time push, not polling. YouTube's hub calls you the moment a video changes.
• No API key, no quota. There is nothing to provision and nothing to run out of.
• Async and sync. Use AsyncYouTubeNotifier, or YouTubeNotifier if you don't run an event loop.
• Listeners for every event. Register @notifier.upload(), @notifier.edit(), @notifier.delete() or @notifier.any(), globally or per channel.
• Brings its own server, or joins yours. Pass your existing FastAPI app and ytnoti mounts onto it.
• Verified callbacks. Every notification is checked against an HMAC signature before a listener sees it.

🛠️ How it works

This library uses YouTube Data API v3 via WebSub (called PubSubHubbub in YouTube's docs) to receive push notifications, so you can receive notifications in real time without constantly polling the YouTube API.

💻 Installation

This library requires Python 3.11 or higher.

pip install ytnoti

📖 Simple Example

Following is a simple example of how to use ngrok to receive push notifications (not recommended for production).

from pyngrok import ngrok
from ytnoti import YouTubeNotifier, Video

ngrok.set_auth_token("Your ngrok token here")

notifier = YouTubeNotifier()


@notifier.upload()
async def listener(video: Video) -> None:
    print(f"New video from {video.channel.name}: {video.title}")


notifier.subscribe("UCuFFtHWoLl5fauMMD5Ww2jA")  # Channel ID of CBC News
notifier.run()

Following is a simple example of how to use your domain to receive push notifications.

from ytnoti import YouTubeNotifier, Video

notifier = YouTubeNotifier(callback_url="https://yourdomain.com")


@notifier.upload()
async def listener(video: Video) -> None:
    print(f"New video from {video.channel.name}: {video.title}")


notifier.subscribe("UCuFFtHWoLl5fauMMD5Ww2jA")  # Channel ID of CBC News
notifier.run()

For more examples, please visit the examples folder.

📚 Documentation

Please read the documentation before asking questions. Your question may already be answered there.

👥 Community

If you are having any problems with using this library, please feel free to ask for help in the issues section or on my Discord server.

🤝 Contributing

Contributions of every size are welcome, whether it's a bug report, a typo fix in the docs, or a new feature. Read CONTRIBUTING.md to set up the project with uv in a few commands, or browse the good first issues to find somewhere to start.

🌟 Contributors

Thanks to everyone who has contributed to ytnoti!

📄 License

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