📺 ShinTube API

A FastAPI backend that uses yt-dlp to provide a RESTful API for fetching video metadata, search results, playlists, comments, and subtitles from YouTube.

---

✨ Features

• Search YouTube videos (/search) with pagination.
• Get comprehensive video details including formats, thumbnails, and chapters (/videos/{id}).
• Fetch video comments (/videos/{id}/comments).
• Retrieve available video subtitles (/videos/{id}/subtitles).
• Fetch playlist metadata and all its videos (/playlists/{id}).
• Get comprehensive channel details (/channels/{id}).
• Fetch a channel's videos with an optional limit (/channels/{id}/videos).
• Built with FastAPI for high performance.
• Asynchronous support for non-blocking requests.
• CORS enabled for easy frontend integration.
• Clean, modular, and scalable project structure.
• Containerized with Docker for easy setup and deployment.

---

📂 Project Structure

ShinTube-API/
├── .dockerignore
├── .gitignore
├── config.py                  # Settings and environment variables
├── docker-compose.yml         # Docker Compose configuration
├── Dockerfile                 # Docker configuration
├── main.py                    # FastAPI application entrypoint
├── README.md
├── requirements.txt           # Python dependencies
├── logs/                      # Log files
├── routes/                    # API endpoints (routers)
│   ├── __init__.py
│   ├── channels.py
│   ├── playlists.py
│   ├── search.py
│   └── videos.py
├── services/                  # Business logic
│   ├── __init__.py
│   ├── cache_service.py
│   └── ytdlp_service.py
└── utils/                     # Helper functions and utilities
    ├── __init__.py
    ├── exceptions.py
    ├── format_parser.py
    └── logger.py

---

🚀 Getting Started

You can run the project using Docker (recommended) or by setting up a local Python environment.

1. Using Docker (Recommended)

Prerequisites:

• Docker and Docker Compose installed.

Instructions:

1. Clone the repository:

   git clone https://github.com/MAyman007/ShinTube-API.git
   cd ShinTube-API

2. Build and run the container using Docker Compose:

   docker-compose up --build

The API will be running and accessible at http://localhost:8000.

2. Local Python Environment

Prerequisites:

• Python 3.8+
• yt-dlp installed and available in your system's PATH.

Instructions:

1. Clone the repository:

   git clone https://github.com/MAyman007/ShinTube-API.git
   cd ShinTube-API

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install the required Python dependencies:

   pip install -r requirements.txt

4. Run the FastAPI server:

   uvicorn main:app --host 0.0.0.0 --port 8000 --reload

---

🌐 API Endpoints

The API documentation is automatically generated by Swagger UI and is available at http://localhost:8000/docs.

Method	Endpoint	Description
GET	/	Health check for the API.
GET	/search	Search for YouTube videos.
GET	/videos/{video_id}	Get details for a specific video.
GET	/videos/{video_id}/comments	Get comments for a specific video.
GET	/videos/{video_id}/subtitles	Get subtitles for a specific video.
GET	/playlists/{playlist_id}	Get metadata and videos for a playlist.
GET	/channels/{channel_id}	Get details for a specific channel.
GET	/channels/{channel_id}/videos	Get videos for a specific channel.

Example Requests

Search for videos: GET /search?q=fastapi&limit=5&page=1

Get video information: GET /videos/dQw4w9WgXcQ

Get video comments: GET /videos/dQw4w9WgXcQ/comments

Get video subtitles: GET /videos/dQw4w9WgXcQ/subtitles

Get playlist information: GET /playlists/PL_z_8CaS__t1_TMImq_vrmAbq8i52j_8G

Get channel information: GET /channels/UC5i3MpHBispO_IzpHbe9E_w

Get channel videos: GET /channels/UC5i3MpHBispO_IzpHbe9E_w/videos?limit=10

---

⚙️ Environment Variables

The application can be configured using environment variables. You can create a .env file in the root directory to manage them.

Variable	Default Value	Description
API_NAME	ShinTube API	The name of the API.
HOST	0.0.0.0	The host address for the server.
PORT	8000	The port for the server.
DEBUG	True	Toggles debug mode.
ALLOWED_ORIGINS	["*"]	A list of allowed CORS origins.

Example .env file:

API_NAME="My ShinTube API"
HOST="0.0.0.0"
PORT=8000
DEBUG=False
ALLOWED_ORIGINS='["http://localhost:3000", "https://my-frontend.com"]'

---

📝 Notes

• This project acts as a wrapper around the yt-dlp command-line tool. Its functionality is dependent on yt-dlp.
• YouTube's structure can change, which may break yt-dlp. Keep yt-dlp updated to ensure the API remains functional.
• This project does not bypass any of YouTube's Terms of Service; it only retrieves publicly available data.

---

🤝 Contributing

Contributions are welcome! To contribute:

1. Fork the repository.
2. Create a new feature branch (git checkout -b feature/YourFeature).
3. Make your changes and commit them (git commit -m 'Add some feature').
4. Push to the branch (git push origin feature/YourFeature).
5. Open a Pull Request.