## StreamSnapper
StreamSnapper is an intuitive library designed to simplify, enhance, and organize media downloads from a variety of audiovisual platforms. It offers efficient, high-speed media extraction with optional tools for extracting data from these platforms.
#### Installation (from [PyPI](https://pypi.org/project/streamsnapper))
```bash
pip install -U streamsnapper # It does not have any features by default, but it can be extended with optional features
pip install -U streamsnapper[downloader] # It has the feature of downloading online content with support for multiple simultaneous connections
pip install -U streamsnapper[merger] # It has the feature of merging video files with audio files using FFmpeg (currently it does not need any dependencies)
pip install -U streamsnapper[youtube] # It has advanced features to extract data from YouTube, with support for several other features
pip install -U streamsnapper[all] # It has all features available at once
```
### Example Usage
#### `streamsnapper[downloader]`
```python
from streamsnapper import Downloader
from pathlib import Path # Optional
# A class for downloading direct download URLs.
downloader = Downloader(
# Initialize the Downloader class with the required settings for downloading a file.
max_connections='auto', # The maximum number of connections to use for downloading the file. (default: 'auto')
connection_speed='auto', # The connection speed in Mbps. If 'auto', the connection speed will be set to 80 Mbps. (default: 'auto')
overwrite=True, # Overwrite the file if it already exists. Otherwise, a "_1", "_2", etc. suffix will be added. (default: True)
show_progress_bar=True, # Show or hide the download progress bar. (default: True)
headers=None, # Custom headers to include in the request. If None, default headers will be used. (default: None)
timeout=None # Timeout in seconds for the download process. Or None for no timeout. (default: None)
)
# Downloads a file from the provided URL to the output file path.
# - If the output_path is a directory, the file name will be generated from the server response.
# - If the output_path is a file, the file will be saved with the provided name.
# - If not provided, the file will be saved to the current working directory.
downloader.download(
url='https://example.com/file', # The download URL to download the file from. (required)
output_path=Path.cwd() # The path to save the downloaded file to. If the path is a directory, the file name will be generated from the server response. If the path is a file, the file will be saved with the provided name. If not provided, the file will be saved to the current working directory. (default: Path.cwd())
)
# All functions are documented and have detailed typings, use your development IDE to learn more.
```
#### `streamsnapper[merger]`
```python
from streamsnapper import Merger
# A class for merging multiple audio and video streams into a single file.
merger = Merger(
# Initialize the Merger class with the required settings for merging audio and video streams.
logging=False # Enable or disable FFmpeg logging. (default: False)
)
# Merge the video and audio streams into a single file.
merger.merge(
video_path='path/to/video', # The path to the video file to merge. (required)
audio_path='path/to/audio', # The path to the audio file to merge. (required)
output_path='path/to/output', # The path to save the output file to. (required)
ffmpeg_path='local' # The path to the FFmpeg executable. If 'local', the FFmpeg executable will be searched in the PATH environment variable. (default: 'local')
)
# All functions are documented and have detailed typings, use your development IDE to learn more.
```
#### `streamsnapper[youtube]`
```python
from streamsnapper import YouTube
from pathlib import Path # Optional
# A class for extracting and formatting data from YouTube videos, facilitating access to general video information, video streams, audio streams and subtitles.
youtube = YouTube(
# Initialize the YouTube class with the required settings for extracting and formatting data from YouTube videos (raw data provided by yt-dlp library).
logging=False # Enable or disable logging for the YouTube class. Defaults to False. (default: False)
)
# Extract the YouTube video data from a URL or provided previously extracted yt-dlp data.
# - If a URL is provided, it will be used to scrape the YouTube video data.
# - If yt-dlp data is provided, it will be used directly.
# - If both URL and yt-dlp data are provided, the yt-dlp data will be used.
youtube.extract(
url=None, # The YouTube video URL to extract data from. (default: None)
ytdlp_data=None # The previously extracted yt-dlp data. (default: None)
)
# Analyze the general information of the YouTube video.
youtube.analyze(
check_thumbnails=False, # Check if all video thumbnails are available. (default: False)
retrieve_dislike_count=False # Retrieve the dislike count from the returnyoutubedislike.com API. (default: False)
)
# Analyze the video streams of the YouTube video and select the best stream based on the preferred quality.
youtube.analyze_video_streams(
preferred_quality='all' # The preferred quality of the video stream. If a specific quality is provided, the stream will be selected according to the chosen quality, however if the quality is not available, the best quality will be selected. If 'all', all streams will be considered and sorted by quality. (default: 'all')
)
# Analyze the audio streams of the YouTube video and select the best stream based on the preferred quality.
youtube.analyze_audio_streams(
preferred_language='local' # The preferred language for the audio stream. If 'source', use the original audio language. If 'local', use the system language. If 'all', return all available audio streams. (default: 'local')
)
# Analyze the subtitle streams of the YouTube video.
youtube.analyze_subtitle_streams()
# Download the YouTube video and/or audio using the provided streams.
# - If no streams are provided, the best video and/or audio streams will be used.
# - If one stream is provided, it will be used to download the # video or audio, without merging.
# - If both streams are provided, they will be merged into a single file.
youtube.download(
video_stream=None, # The video stream generated by .analyze_video_streams(). (default: None)
audio_stream=None, # The audio stream generated by .analyze_audio_streams(). (default: None)
output_path=Path.cwd(), # The output path to save the downloaded video and/or audio to. If a directory is provided, the file name will be generated based on the video title and ID, like 'title - [id].extension'. If a file is provided, the file will be saved with the provided name. (default: Path.cwd())
ffmpeg_path='local', # The path to the ffmpeg executable. If 'local', the ffmpeg executable will be searched in the PATH environment variable. (default: 'local')
show_progress_bar=True, # Show or hide the download progress bar. (default: True)
timeout=None, # Timeout in seconds for the download process. Or None for no timeout. (default: None)
logging=False # Enable or disable ffmpeg logging. (default: False)
) # --> Returns the Path object of the finished file.
from streamsnapper import YouTubeExtractor
# A class for extracting data from YouTube URLs and searching for YouTube videos.
youtube_extractor = YouTubeExtractor(
# Initialize the Extractor class with some regular expressions for analyzing YouTube URLs.
)
# Identify the platform of a given URL as either YouTube or YouTube Music.
youtube_extractor.identify_platform(
url='https://music.youtube.com/watch?v=***********' # The URL to identify the platform from. (required)
) # --> Returns 'youtube' if the URL corresponds to YouTube, 'youtubeMusic' if it corresponds to YouTube Music. Returns None if the platform is not recognized.
# Extract the YouTube video ID from a URL.
youtube_extractor.extract_video_id(
url='https://www.youtube.com/watch?v=***********' # The URL to extract the video ID from. (required)
) # --> Returns the extracted video ID. If no video ID is found, return None.
# Extract the YouTube playlist ID from a URL.
youtube_extractor.extract_playlist_id(
url='https://www.youtube.com/playlist?list=**********************************', # The URL to extract the playlist ID from. (required)
include_private=False # Whether to include private playlists, like the mixes YouTube makes for you. (default: False)
) # --> Returns the extracted playlist ID. If no playlist ID is found or the playlist is private and include_private is False, return None.
# Search for YouTube content based on a query and return a list of URLs (raw data provided by scrapetube library).
youtube_extractor.search(
query='A cool music name', # The search query string. (required)
sort_by='relevance', # The sorting method to use for the search results. Options are 'relevance', 'upload_date', 'view_count', and 'rating'. (default: 'relevance')
results_type='video', # The type of content to search for. Options are 'video', 'channel', 'playlist', and 'movie'. (default: 'video')
limit=1 # The maximum number of video URLs to return. (default: 1)
) # --> Returns a list of video URLs from the search results. If no videos are found, returns None.
# Get the video URLs from a YouTube playlist (raw data provided by scrapetube library).
youtube_extractor.get_playlist_videos(
url='https://www.youtube.com/playlist?list=**********************************', # The URL of the YouTube playlist. (required)
limit=None # The maximum number of video URLs to return. If None, return all video URLs. (default: None)
) # --> Returns a list of video URLs from the playlist. If no videos are found or the playlist is private, return None.
# Get the video URLs from a YouTube channel (raw data provided by scrapetube library).
# - If channel_id, channel_url, and channel_username are all None, return None.
# - If more than one of channel_id, channel_url, and channel_username is provided, raise ValueError.
youtube_extractor.get_channel_videos(
channel_id='************************', # The ID of the YouTube channel. (default: None)
channel_url='https://www.youtube.com/@********', # The URL of the YouTube channel. (default: None)
channel_username='********', # The username of the YouTube channel. (default: None)
sort_by='newest', # The sorting method to use for the channel videos. Options are 'newest', 'oldest', and 'popular' (default: 'newest').
content_type='videos', # The type of content to search for. Options are 'videos', 'shorts', and 'streams' (default: 'videos').
limit=None # The maximum number of video URLs to return. If None, return all video URLs. (default: None)
) # --> Returns a list of video URLs from the channel. If no videos are found or the channel is non-existent, return None.
# All functions are documented and have detailed typings, use your development IDE to learn more.
```
### Contributing
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
If you have a suggestion that would make this better, fork the repository and create a pull request. You can also simply open an issue and describe your ideas or report bugs. **Don't forget to give the project a star if you like it!**
1. Fork the project;
2. Create your feature branch ・ `git checkout -b feature/{feature_name}`;
3. Commit your changes ・ `git commit -m "{commit_message}"`;
4. Push to the branch ・ `git push origin feature/{feature_name}`;
5. Open a pull request, describing the changes you made and wait for a review.
### Disclaimer
Please note that downloading copyrighted content from some media services may be illegal in your country. This tool is designed for educational purposes only. Use at your own risk.
Raw data
{
"_id": null,
"home_page": "https://github.com/henrique-coder/streamsnapper",
"name": "streamsnapper",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "stream, snapper, scraper, downloader, merger, youtube",
"author": "henrique-coder",
"author_email": "hjyz6rqyb@mozmail.com",
"download_url": "https://files.pythonhosted.org/packages/e0/b0/3c3c69a255ee2dc50cc308e021c4a074f0b8d4663cd8ba51d2fd0a0a10d9/streamsnapper-0.2.5.tar.gz",
"platform": null,
"description": "## StreamSnapper\n\nStreamSnapper is an intuitive library designed to simplify, enhance, and organize media downloads from a variety of audiovisual platforms. It offers efficient, high-speed media extraction with optional tools for extracting data from these platforms.\n\n\n\n\n\n\n\n#### Installation (from [PyPI](https://pypi.org/project/streamsnapper))\n\n```bash\npip install -U streamsnapper # It does not have any features by default, but it can be extended with optional features\npip install -U streamsnapper[downloader] # It has the feature of downloading online content with support for multiple simultaneous connections\npip install -U streamsnapper[merger] # It has the feature of merging video files with audio files using FFmpeg (currently it does not need any dependencies)\npip install -U streamsnapper[youtube] # It has advanced features to extract data from YouTube, with support for several other features\npip install -U streamsnapper[all] # It has all features available at once\n```\n\n### Example Usage\n\n#### `streamsnapper[downloader]`\n\n```python\nfrom streamsnapper import Downloader\nfrom pathlib import Path # Optional\n\n\n# A class for downloading direct download URLs.\ndownloader = Downloader(\n # Initialize the Downloader class with the required settings for downloading a file.\n max_connections='auto', # The maximum number of connections to use for downloading the file. (default: 'auto')\n connection_speed='auto', # The connection speed in Mbps. If 'auto', the connection speed will be set to 80 Mbps. (default: 'auto')\n overwrite=True, # Overwrite the file if it already exists. Otherwise, a \"_1\", \"_2\", etc. suffix will be added. (default: True)\n show_progress_bar=True, # Show or hide the download progress bar. (default: True)\n headers=None, # Custom headers to include in the request. If None, default headers will be used. (default: None)\n timeout=None # Timeout in seconds for the download process. Or None for no timeout. (default: None)\n)\n\n# Downloads a file from the provided URL to the output file path.\n# - If the output_path is a directory, the file name will be generated from the server response.\n# - If the output_path is a file, the file will be saved with the provided name.\n# - If not provided, the file will be saved to the current working directory.\ndownloader.download(\n url='https://example.com/file', # The download URL to download the file from. (required)\n output_path=Path.cwd() # The path to save the downloaded file to. If the path is a directory, the file name will be generated from the server response. If the path is a file, the file will be saved with the provided name. If not provided, the file will be saved to the current working directory. (default: Path.cwd())\n)\n\n# All functions are documented and have detailed typings, use your development IDE to learn more.\n\n```\n\n#### `streamsnapper[merger]`\n\n```python\nfrom streamsnapper import Merger\n\n\n# A class for merging multiple audio and video streams into a single file.\nmerger = Merger(\n # Initialize the Merger class with the required settings for merging audio and video streams.\n logging=False # Enable or disable FFmpeg logging. (default: False)\n)\n\n# Merge the video and audio streams into a single file.\nmerger.merge(\n video_path='path/to/video', # The path to the video file to merge. (required)\n audio_path='path/to/audio', # The path to the audio file to merge. (required)\n output_path='path/to/output', # The path to save the output file to. (required)\n ffmpeg_path='local' # The path to the FFmpeg executable. If 'local', the FFmpeg executable will be searched in the PATH environment variable. (default: 'local')\n)\n\n# All functions are documented and have detailed typings, use your development IDE to learn more.\n\n```\n\n#### `streamsnapper[youtube]`\n\n```python\nfrom streamsnapper import YouTube\nfrom pathlib import Path # Optional\n\n\n# A class for extracting and formatting data from YouTube videos, facilitating access to general video information, video streams, audio streams and subtitles.\nyoutube = YouTube(\n # Initialize the YouTube class with the required settings for extracting and formatting data from YouTube videos (raw data provided by yt-dlp library).\n logging=False # Enable or disable logging for the YouTube class. Defaults to False. (default: False)\n)\n\n# Extract the YouTube video data from a URL or provided previously extracted yt-dlp data.\n# - If a URL is provided, it will be used to scrape the YouTube video data.\n# - If yt-dlp data is provided, it will be used directly.\n# - If both URL and yt-dlp data are provided, the yt-dlp data will be used.\nyoutube.extract(\n url=None, # The YouTube video URL to extract data from. (default: None)\n ytdlp_data=None # The previously extracted yt-dlp data. (default: None)\n)\n\n# Analyze the general information of the YouTube video.\nyoutube.analyze(\n check_thumbnails=False, # Check if all video thumbnails are available. (default: False)\n retrieve_dislike_count=False # Retrieve the dislike count from the returnyoutubedislike.com API. (default: False)\n)\n\n# Analyze the video streams of the YouTube video and select the best stream based on the preferred quality.\nyoutube.analyze_video_streams(\n preferred_quality='all' # The preferred quality of the video stream. If a specific quality is provided, the stream will be selected according to the chosen quality, however if the quality is not available, the best quality will be selected. If 'all', all streams will be considered and sorted by quality. (default: 'all')\n)\n\n# Analyze the audio streams of the YouTube video and select the best stream based on the preferred quality.\nyoutube.analyze_audio_streams(\n preferred_language='local' # The preferred language for the audio stream. If 'source', use the original audio language. If 'local', use the system language. If 'all', return all available audio streams. (default: 'local')\n)\n\n# Analyze the subtitle streams of the YouTube video.\nyoutube.analyze_subtitle_streams()\n\n# Download the YouTube video and/or audio using the provided streams.\n# - If no streams are provided, the best video and/or audio streams will be used.\n# - If one stream is provided, it will be used to download the # video or audio, without merging.\n# - If both streams are provided, they will be merged into a single file.\nyoutube.download(\n video_stream=None, # The video stream generated by .analyze_video_streams(). (default: None)\n audio_stream=None, # The audio stream generated by .analyze_audio_streams(). (default: None)\n output_path=Path.cwd(), # The output path to save the downloaded video and/or audio to. If a directory is provided, the file name will be generated based on the video title and ID, like 'title - [id].extension'. If a file is provided, the file will be saved with the provided name. (default: Path.cwd())\n ffmpeg_path='local', # The path to the ffmpeg executable. If 'local', the ffmpeg executable will be searched in the PATH environment variable. (default: 'local')\n show_progress_bar=True, # Show or hide the download progress bar. (default: True)\n timeout=None, # Timeout in seconds for the download process. Or None for no timeout. (default: None)\n logging=False # Enable or disable ffmpeg logging. (default: False)\n) # --> Returns the Path object of the finished file.\n\n\nfrom streamsnapper import YouTubeExtractor\n\n\n# A class for extracting data from YouTube URLs and searching for YouTube videos.\nyoutube_extractor = YouTubeExtractor(\n # Initialize the Extractor class with some regular expressions for analyzing YouTube URLs.\n)\n\n# Identify the platform of a given URL as either YouTube or YouTube Music.\nyoutube_extractor.identify_platform(\n url='https://music.youtube.com/watch?v=***********' # The URL to identify the platform from. (required)\n) # --> Returns 'youtube' if the URL corresponds to YouTube, 'youtubeMusic' if it corresponds to YouTube Music. Returns None if the platform is not recognized.\n\n# Extract the YouTube video ID from a URL.\nyoutube_extractor.extract_video_id(\n url='https://www.youtube.com/watch?v=***********' # The URL to extract the video ID from. (required)\n) # --> Returns the extracted video ID. If no video ID is found, return None.\n\n# Extract the YouTube playlist ID from a URL.\nyoutube_extractor.extract_playlist_id(\n url='https://www.youtube.com/playlist?list=**********************************', # The URL to extract the playlist ID from. (required)\n include_private=False # Whether to include private playlists, like the mixes YouTube makes for you. (default: False)\n) # --> Returns the extracted playlist ID. If no playlist ID is found or the playlist is private and include_private is False, return None.\n\n# Search for YouTube content based on a query and return a list of URLs (raw data provided by scrapetube library).\nyoutube_extractor.search(\n query='A cool music name', # The search query string. (required)\n sort_by='relevance', # The sorting method to use for the search results. Options are 'relevance', 'upload_date', 'view_count', and 'rating'. (default: 'relevance')\n results_type='video', # The type of content to search for. Options are 'video', 'channel', 'playlist', and 'movie'. (default: 'video')\n limit=1 # The maximum number of video URLs to return. (default: 1)\n) # --> Returns a list of video URLs from the search results. If no videos are found, returns None.\n\n# Get the video URLs from a YouTube playlist (raw data provided by scrapetube library).\nyoutube_extractor.get_playlist_videos(\n url='https://www.youtube.com/playlist?list=**********************************', # The URL of the YouTube playlist. (required)\n limit=None # The maximum number of video URLs to return. If None, return all video URLs. (default: None)\n) # --> Returns a list of video URLs from the playlist. If no videos are found or the playlist is private, return None.\n\n# Get the video URLs from a YouTube channel (raw data provided by scrapetube library).\n# - If channel_id, channel_url, and channel_username are all None, return None.\n# - If more than one of channel_id, channel_url, and channel_username is provided, raise ValueError.\nyoutube_extractor.get_channel_videos(\n channel_id='************************', # The ID of the YouTube channel. (default: None)\n channel_url='https://www.youtube.com/@********', # The URL of the YouTube channel. (default: None)\n channel_username='********', # The username of the YouTube channel. (default: None)\n sort_by='newest', # The sorting method to use for the channel videos. Options are 'newest', 'oldest', and 'popular' (default: 'newest').\n content_type='videos', # The type of content to search for. Options are 'videos', 'shorts', and 'streams' (default: 'videos').\n limit=None # The maximum number of video URLs to return. If None, return all video URLs. (default: None)\n) # --> Returns a list of video URLs from the channel. If no videos are found or the channel is non-existent, return None.\n\n# All functions are documented and have detailed typings, use your development IDE to learn more.\n\n```\n\n### Contributing\n\nContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\nIf you have a suggestion that would make this better, fork the repository and create a pull request. You can also simply open an issue and describe your ideas or report bugs. **Don't forget to give the project a star if you like it!**\n\n1. Fork the project;\n2. Create your feature branch \u30fb `git checkout -b feature/{feature_name}`;\n3. Commit your changes \u30fb `git commit -m \"{commit_message}\"`;\n4. Push to the branch \u30fb `git push origin feature/{feature_name}`;\n5. Open a pull request, describing the changes you made and wait for a review.\n\n### Disclaimer\n\nPlease note that downloading copyrighted content from some media services may be illegal in your country. This tool is designed for educational purposes only. Use at your own risk.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "StreamSnapper is an intuitive library designed to simplify, enhance, and organize media downloads from a variety of audiovisual platforms. It offers efficient, high-speed media extraction with optional tools for extracting data from these platforms.",
"version": "0.2.5",
"project_urls": {
"Documentation": "https://github.com/henrique-coder/streamsnapper",
"Homepage": "https://github.com/henrique-coder/streamsnapper",
"Repository": "https://github.com/henrique-coder/streamsnapper"
},
"split_keywords": [
"stream",
" snapper",
" scraper",
" downloader",
" merger",
" youtube"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "19baa2ddecc209d174cc6a75d48b1d6022079b1a479d88cd2fda08415a3e40d8",
"md5": "9499dd7b887f50191627e92d498c18f7",
"sha256": "3ae0bb0966c7c62ead2ba13bbb58ff4f476a9e643f8be71acc7ee4d71cf4fd97"
},
"downloads": -1,
"filename": "streamsnapper-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9499dd7b887f50191627e92d498c18f7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 20134,
"upload_time": "2024-12-16T22:46:26",
"upload_time_iso_8601": "2024-12-16T22:46:26.063312Z",
"url": "https://files.pythonhosted.org/packages/19/ba/a2ddecc209d174cc6a75d48b1d6022079b1a479d88cd2fda08415a3e40d8/streamsnapper-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e0b03c3c69a255ee2dc50cc308e021c4a074f0b8d4663cd8ba51d2fd0a0a10d9",
"md5": "fb8495837471a16f4b2b8f222ba738ce",
"sha256": "f8cd4d06c137d571ae026e1b068a4230ae6f88536d8c8ce79608dd000ad87da2"
},
"downloads": -1,
"filename": "streamsnapper-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "fb8495837471a16f4b2b8f222ba738ce",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 20146,
"upload_time": "2024-12-16T22:46:28",
"upload_time_iso_8601": "2024-12-16T22:46:28.892710Z",
"url": "https://files.pythonhosted.org/packages/e0/b0/3c3c69a255ee2dc50cc308e021c4a074f0b8d4663cd8ba51d2fd0a0a10d9/streamsnapper-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-16 22:46:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "henrique-coder",
"github_project": "streamsnapper",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "httpx",
"specs": [
[
"==",
"0.28.1"
]
]
},
{
"name": "rich",
"specs": [
[
"==",
"13.9.4"
]
]
},
{
"name": "scrapetube",
"specs": [
[
"==",
"2.5.1"
]
]
},
{
"name": "yt-dlp",
"specs": [
[
"==",
"2024.12.13"
]
]
}
],
"lcname": "streamsnapper"
}
JSON
