"""
# YouTube & YouTube Music API
A powerful, lightweight, and high-performance API for accessing YouTube and YouTube Music content, metadata, and streams. Designed for simplicity and flexibility, this library provides full access to YouTube sources, including videos, playlists, metadata, and more.
"""
# Features
# - Fetch videos, playlists, and metadata from YouTube and YouTube Music.
# - Retrieve lyrics, related tracks, and detailed metadata.
# Hydra YouTube API Documentation
## Installation
To use the Hydra YouTube API, you can install it via pip:
```bash
pip install hydra_youtube_api
```
## Command-Line Interface (CLI)
Once installed, you can use the CLI tool `hydra-yt` to fetch YouTube video and audio data.
### Usage
```bash
hydra-yt <video_id> [options]
```
### Arguments
- **`video_id`**: The YouTube video ID you want to fetch data for.
### Options
- **`--bestaudio`**: Fetch the best audio format.
- **`--bestvideo`**: Fetch the best video format.
- **`--lowestaudio`**: Fetch the lowest quality audio format.
- **`--lowestvideo`**: Fetch the lowest quality video format.
- **`--videoandaudio`**: Fetch a format containing both video and audio.
- **`--videoonly`**: Fetch a video-only format.
- **`--audioonly`**: Fetch an audio-only format.
- **`--lyrics`**: Fetch lyrics for the video (if available).
- **`--ms`**: Measure and print the total time taken for the process.
### Example
```bash
hydra-yt dQw4w9WgXcQ --bestaudio
```
This command fetches the best audio format for the video with ID `dQw4w9WgXcQ`.
## API Reference
### `get_data`
#### Description
Fetches detailed data for a given YouTube video, including formats and metadata.
#### Signature
```python
async def get_data(video_id, is_raw=False, client_name='ios')
```
#### Parameters
- **`video_id` (str)**: The ID of the YouTube video to fetch data for.
- **`is_raw` (bool, optional)**: If `True`, returns raw API response data. Defaults to `False`.
- **`client_name` (str, optional)**: Specifies the client type (`'ios'` or `'android'`). Defaults to `'ios'`.
#### Returns
- **`dict`**: Parsed video formats and metadata if `is_raw=False`.
- **`dict`**: Raw API response if `is_raw=True`.
#### Example
```python
from hydra_youtube_api.sources import get_data
import asyncio
async def fetch_video_data():
video_id = "dQw4w9WgXcQ"
data = await get_data(video_id, is_raw=False, client_name='ios')
print(data)
asyncio.run(fetch_video_data())
```
### `filter_formats`
#### Description
Filters video and audio formats from the raw or parsed video data.
#### Signature
```python
def filter_formats(formats, filter_type='all', options=None)
```
#### Parameters
- **`formats` (list)**: The list of formats to filter.
- **`filter_type` (str)**: The type of filter to apply. Options include:
- `'all'`
- `'bestvideo'`
- `'bestaudio'`
- `'lowestvideo'`
- `'lowestaudio'`
- `'videoandaudio'`
- `'videoonly'`
- `'audioonly'`
- **`options` (dict, optional)**: Additional filter options, such as:
- `'fallback'` (bool): Whether to return a fallback format if no formats match.
- `'customSort'` (callable): Custom sorting function.
- `'minBitrate'` (int): Minimum bitrate in bps.
- `'minResolution'` (int): Minimum resolution in pixels.
- `'codec'` (str): Specific codec to filter by.
#### Returns
- **`list` or `dict`**: Filtered formats based on the specified filter type.
#### Example
```python
from hydra_youtube_api.sources import filter_formats
formats = [
{"mimeType": "audio/mp4", "bitrate": 128000},
{"mimeType": "video/mp4", "width": 1920, "height": 1080, "bitrate": 5000000}
]
best_audio = filter_formats(formats, filter_type='bestaudio')
print(best_audio)
```
from typing import Union, List, Dict, Any
# Core Functions
async def get_video_id(q: str, is_youtube: bool) -> Union[str, Dict[str, str]]:
"""
Retrieves the YouTube video ID for a given song or title.
Parameters:
- q (str): The search query (e.g., song name or title).
- is_youtube (bool): If true, searches YouTube; otherwise, searches YouTube Music.
Returns:
- str | Dict: The video ID or an error object.
"""
pass
async def get_youtube_list(id: str) -> Union[Dict[str, Any], Dict[str, str]]:
"""
Fetches metadata and tracks for a YouTube playlist.
Parameters:
- id (str): The ID of the YouTube playlist.
Returns:
- Dict: Playlist metadata and track list or an error object.
"""
pass
async def get_youtube_music_list(id: str) -> Union[Dict[str, Any], Dict[str, str]]:
"""
Fetches metadata and tracks for a YouTube Music playlist.
Parameters:
- id (str): The ID of the YouTube Music playlist.
Returns:
- Dict: Playlist metadata and track list or an error object.
"""
pass
async def youtube_music_search(q: str, method: str = 'songs') -> Union[List[Any], Dict[str, str]]:
"""
Searches YouTube Music for songs, artists, albums, or playlists.
Parameters:
- q (str): The search query.
- method (str): The search category (songs, artists, albums, etc.).
Returns:
- List | Dict: An array of search results or an error object.
"""
pass
async def get_related_and_lyrics(id: str) -> Union[Dict[str, Any], Dict[str, str]]:
"""
Fetches related tracks, playlist queue, and lyrics for a given video ID.
Parameters:
- id (str): The YouTube video ID.
Returns:
- Dict: Related tracks, playlist queue, and lyrics data or an error object.
"""
pass
async def get_lyrics(id: str) -> Union[str, Dict[str, str]]:
"""
Fetches lyrics for a specific video ID.
Parameters:
- id (str): The YouTube video ID.
Returns:
- str | Dict: Lyrics or an error object.
"""
pass
async def get_yt_music_related(id: str) -> Union[Any, Dict[str, str]]:
"""
Fetches related tracks for YouTube Music based on the provided ID.
Parameters:
- id (str): The ID of the track.
Returns:
- Any | Dict: Related track details or an error object.
"""
pass
async def get_artist(id: str) -> Union[Any, Dict[str, str]]:
"""
Fetches information about an artist.
Parameters:
- id (str): The artist ID.
Returns:
- Any | Dict: Artist details or an error object.
"""
pass
async def get_album(id: str) -> Union[Any, Dict[str, str]]:
"""
Fetches information about an album.
Parameters:
- id (str): The album ID.
Returns:
- Any | Dict: Album details or an error object.
"""
pass
async def get_track_data(id: str) -> Union[Dict[str, Any], Dict[str, str]]:
"""
Fetches detailed track data, including artist, album, duration, and poster information.
Parameters:
- id (str): The track ID.
Returns:
- Dict: Track metadata and details or an error object.
"""
pass
async def get_podcast(id: str) -> Union[Any, Dict[str, str]]:
"""
Fetches details about a podcast.
Parameters:
- id (str): The podcast ID.
Returns:
- Any | Dict: Podcast details or an error object.
"""
pass
Raw data
{
"_id": null,
"home_page": "https://github.com/Hydralerne/youtube-api",
"name": "hydra-youtube-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "youtube, music, api, metadata, downloader",
"author": "Hydra de lerne",
"author_email": "hydra@onvo.me",
"download_url": "https://files.pythonhosted.org/packages/02/12/7c2f8ae7c46ee46f12e12fdae4c50d8b87eef29aab96271eb2a80b2a3d1d/hydra_youtube_api-1.1.5.tar.gz",
"platform": null,
"description": "\"\"\"\r\n# YouTube & YouTube Music API\r\n\r\nA powerful, lightweight, and high-performance API for accessing YouTube and YouTube Music content, metadata, and streams. Designed for simplicity and flexibility, this library provides full access to YouTube sources, including videos, playlists, metadata, and more.\r\n\"\"\"\r\n\r\n# Features\r\n# - Fetch videos, playlists, and metadata from YouTube and YouTube Music.\r\n# - Retrieve lyrics, related tracks, and detailed metadata.\r\n\r\n# Hydra YouTube API Documentation\r\n\r\n## Installation\r\nTo use the Hydra YouTube API, you can install it via pip:\r\n```bash\r\npip install hydra_youtube_api\r\n```\r\n\r\n## Command-Line Interface (CLI)\r\nOnce installed, you can use the CLI tool `hydra-yt` to fetch YouTube video and audio data.\r\n\r\n### Usage\r\n```bash\r\nhydra-yt <video_id> [options]\r\n```\r\n\r\n### Arguments\r\n- **`video_id`**: The YouTube video ID you want to fetch data for.\r\n\r\n### Options\r\n- **`--bestaudio`**: Fetch the best audio format.\r\n- **`--bestvideo`**: Fetch the best video format.\r\n- **`--lowestaudio`**: Fetch the lowest quality audio format.\r\n- **`--lowestvideo`**: Fetch the lowest quality video format.\r\n- **`--videoandaudio`**: Fetch a format containing both video and audio.\r\n- **`--videoonly`**: Fetch a video-only format.\r\n- **`--audioonly`**: Fetch an audio-only format.\r\n- **`--lyrics`**: Fetch lyrics for the video (if available).\r\n- **`--ms`**: Measure and print the total time taken for the process.\r\n\r\n### Example\r\n```bash\r\nhydra-yt dQw4w9WgXcQ --bestaudio\r\n```\r\nThis command fetches the best audio format for the video with ID `dQw4w9WgXcQ`.\r\n\r\n## API Reference\r\n\r\n### `get_data`\r\n#### Description\r\nFetches detailed data for a given YouTube video, including formats and metadata.\r\n\r\n#### Signature\r\n```python\r\nasync def get_data(video_id, is_raw=False, client_name='ios')\r\n```\r\n\r\n#### Parameters\r\n- **`video_id` (str)**: The ID of the YouTube video to fetch data for.\r\n- **`is_raw` (bool, optional)**: If `True`, returns raw API response data. Defaults to `False`.\r\n- **`client_name` (str, optional)**: Specifies the client type (`'ios'` or `'android'`). Defaults to `'ios'`.\r\n\r\n#### Returns\r\n- **`dict`**: Parsed video formats and metadata if `is_raw=False`.\r\n- **`dict`**: Raw API response if `is_raw=True`.\r\n\r\n#### Example\r\n```python\r\nfrom hydra_youtube_api.sources import get_data\r\nimport asyncio\r\n\r\nasync def fetch_video_data():\r\n video_id = \"dQw4w9WgXcQ\"\r\n data = await get_data(video_id, is_raw=False, client_name='ios')\r\n print(data)\r\n\r\nasyncio.run(fetch_video_data())\r\n```\r\n\r\n### `filter_formats`\r\n#### Description\r\nFilters video and audio formats from the raw or parsed video data.\r\n\r\n#### Signature\r\n```python\r\ndef filter_formats(formats, filter_type='all', options=None)\r\n```\r\n\r\n#### Parameters\r\n- **`formats` (list)**: The list of formats to filter.\r\n- **`filter_type` (str)**: The type of filter to apply. Options include:\r\n - `'all'`\r\n - `'bestvideo'`\r\n - `'bestaudio'`\r\n - `'lowestvideo'`\r\n - `'lowestaudio'`\r\n - `'videoandaudio'`\r\n - `'videoonly'`\r\n - `'audioonly'`\r\n- **`options` (dict, optional)**: Additional filter options, such as:\r\n - `'fallback'` (bool): Whether to return a fallback format if no formats match.\r\n - `'customSort'` (callable): Custom sorting function.\r\n - `'minBitrate'` (int): Minimum bitrate in bps.\r\n - `'minResolution'` (int): Minimum resolution in pixels.\r\n - `'codec'` (str): Specific codec to filter by.\r\n\r\n#### Returns\r\n- **`list` or `dict`**: Filtered formats based on the specified filter type.\r\n\r\n#### Example\r\n```python\r\nfrom hydra_youtube_api.sources import filter_formats\r\n\r\nformats = [\r\n {\"mimeType\": \"audio/mp4\", \"bitrate\": 128000},\r\n {\"mimeType\": \"video/mp4\", \"width\": 1920, \"height\": 1080, \"bitrate\": 5000000}\r\n]\r\n\r\nbest_audio = filter_formats(formats, filter_type='bestaudio')\r\nprint(best_audio)\r\n```\r\n\r\nfrom typing import Union, List, Dict, Any\r\n\r\n# Core Functions\r\n\r\nasync def get_video_id(q: str, is_youtube: bool) -> Union[str, Dict[str, str]]:\r\n \"\"\"\r\n Retrieves the YouTube video ID for a given song or title.\r\n\r\n Parameters:\r\n - q (str): The search query (e.g., song name or title).\r\n - is_youtube (bool): If true, searches YouTube; otherwise, searches YouTube Music.\r\n\r\n Returns:\r\n - str | Dict: The video ID or an error object.\r\n \"\"\"\r\n pass\r\n\r\nasync def get_youtube_list(id: str) -> Union[Dict[str, Any], Dict[str, str]]:\r\n \"\"\"\r\n Fetches metadata and tracks for a YouTube playlist.\r\n\r\n Parameters:\r\n - id (str): The ID of the YouTube playlist.\r\n\r\n Returns:\r\n - Dict: Playlist metadata and track list or an error object.\r\n \"\"\"\r\n pass\r\n\r\nasync def get_youtube_music_list(id: str) -> Union[Dict[str, Any], Dict[str, str]]:\r\n \"\"\"\r\n Fetches metadata and tracks for a YouTube Music playlist.\r\n\r\n Parameters:\r\n - id (str): The ID of the YouTube Music playlist.\r\n\r\n Returns:\r\n - Dict: Playlist metadata and track list or an error object.\r\n \"\"\"\r\n pass\r\n\r\nasync def youtube_music_search(q: str, method: str = 'songs') -> Union[List[Any], Dict[str, str]]:\r\n \"\"\"\r\n Searches YouTube Music for songs, artists, albums, or playlists.\r\n\r\n Parameters:\r\n - q (str): The search query.\r\n - method (str): The search category (songs, artists, albums, etc.).\r\n\r\n Returns:\r\n - List | Dict: An array of search results or an error object.\r\n \"\"\"\r\n pass\r\n\r\nasync def get_related_and_lyrics(id: str) -> Union[Dict[str, Any], Dict[str, str]]:\r\n \"\"\"\r\n Fetches related tracks, playlist queue, and lyrics for a given video ID.\r\n\r\n Parameters:\r\n - id (str): The YouTube video ID.\r\n\r\n Returns:\r\n - Dict: Related tracks, playlist queue, and lyrics data or an error object.\r\n \"\"\"\r\n pass\r\n\r\nasync def get_lyrics(id: str) -> Union[str, Dict[str, str]]:\r\n \"\"\"\r\n Fetches lyrics for a specific video ID.\r\n\r\n Parameters:\r\n - id (str): The YouTube video ID.\r\n\r\n Returns:\r\n - str | Dict: Lyrics or an error object.\r\n \"\"\"\r\n pass\r\n\r\nasync def get_yt_music_related(id: str) -> Union[Any, Dict[str, str]]:\r\n \"\"\"\r\n Fetches related tracks for YouTube Music based on the provided ID.\r\n\r\n Parameters:\r\n - id (str): The ID of the track.\r\n\r\n Returns:\r\n - Any | Dict: Related track details or an error object.\r\n \"\"\"\r\n pass\r\n\r\nasync def get_artist(id: str) -> Union[Any, Dict[str, str]]:\r\n \"\"\"\r\n Fetches information about an artist.\r\n\r\n Parameters:\r\n - id (str): The artist ID.\r\n\r\n Returns:\r\n - Any | Dict: Artist details or an error object.\r\n \"\"\"\r\n pass\r\n\r\nasync def get_album(id: str) -> Union[Any, Dict[str, str]]:\r\n \"\"\"\r\n Fetches information about an album.\r\n\r\n Parameters:\r\n - id (str): The album ID.\r\n\r\n Returns:\r\n - Any | Dict: Album details or an error object.\r\n \"\"\"\r\n pass\r\n\r\nasync def get_track_data(id: str) -> Union[Dict[str, Any], Dict[str, str]]:\r\n \"\"\"\r\n Fetches detailed track data, including artist, album, duration, and poster information.\r\n\r\n Parameters:\r\n - id (str): The track ID.\r\n\r\n Returns:\r\n - Dict: Track metadata and details or an error object.\r\n \"\"\"\r\n pass\r\n\r\nasync def get_podcast(id: str) -> Union[Any, Dict[str, str]]:\r\n \"\"\"\r\n Fetches details about a podcast.\r\n\r\n Parameters:\r\n - id (str): The podcast ID.\r\n\r\n Returns:\r\n - Any | Dict: Podcast details or an error object.\r\n \"\"\"\r\n pass\r\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "Fast and simple API for YouTube and YouTube Music",
"version": "1.1.5",
"project_urls": {
"Homepage": "https://github.com/Hydralerne/youtube-api"
},
"split_keywords": [
"youtube",
" music",
" api",
" metadata",
" downloader"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "408ec7898e82119b9ef2eca71289d4f8eab53d8d0b907c512a124aaf8891212f",
"md5": "3c7040f6bd248006af80056db721c66b",
"sha256": "62c65aaed17662c6f477c4fe457561169e271ce287e2750f261aa116e2847623"
},
"downloads": -1,
"filename": "hydra_youtube_api-1.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3c7040f6bd248006af80056db721c66b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 15799,
"upload_time": "2025-01-03T05:02:17",
"upload_time_iso_8601": "2025-01-03T05:02:17.430964Z",
"url": "https://files.pythonhosted.org/packages/40/8e/c7898e82119b9ef2eca71289d4f8eab53d8d0b907c512a124aaf8891212f/hydra_youtube_api-1.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "02127c2f8ae7c46ee46f12e12fdae4c50d8b87eef29aab96271eb2a80b2a3d1d",
"md5": "02d0b68ffade959138405bf9d31f0417",
"sha256": "e3cb8ffca23a452147af2caa242de05111244b1e6b19e4d3a23a7c37ab7bf2e0"
},
"downloads": -1,
"filename": "hydra_youtube_api-1.1.5.tar.gz",
"has_sig": false,
"md5_digest": "02d0b68ffade959138405bf9d31f0417",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 16800,
"upload_time": "2025-01-03T05:02:19",
"upload_time_iso_8601": "2025-01-03T05:02:19.935358Z",
"url": "https://files.pythonhosted.org/packages/02/12/7c2f8ae7c46ee46f12e12fdae4c50d8b87eef29aab96271eb2a80b2a3d1d/hydra_youtube_api-1.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-03 05:02:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Hydralerne",
"github_project": "youtube-api",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "hydra-youtube-api"
}
JSON
