linkify-media 0.1.0

Async movie/TV metadata fetcher — TMDB, IMDb, RT, Letterboxd

🎬 Linkify-Media

Async TMDB · IMDb · Rotten Tomatoes · Metacritic · Letterboxd
Fast CLI · Clean JSON · Docker Ready · API Ready · Zero 404 RT Links

---

📌 About

Linkify Media is a high-performance Async CLI utility that fetches complete metadata and verified platform links for Movies & TV Series using the TMDB API.

Built for:

• Backend APIs
• Media platforms
• Automation scripts
• Portfolio projects
• Data enrichment pipelines

Powered by:

• ⚡ aiohttp (async requests)
• 🎯 Smart slug generation
• 🛡️ Rotten Tomatoes link validation
• 💾 In-memory caching
• 🖥️ Proper CLI with argparse
• 🐳 Docker support

---

✨ Key Features

Feature	Status	Description
Async Engine	⚡	Concurrent API calls using asyncio
Full Metadata	🎬	Title, Year, Genres, Runtime, Rating
Top Cast Fetching	👥	First 5 credited actors
Poster Support	🖼️	TMDB poster image URL
Multi-Platform Links	🔗	TMDB, IMDb, RT, Metacritic, Letterboxd
RT Validation	🛡️	Prevents broken Rotten Tomatoes URLs
CLI Arguments	🖥️	--media, --json support
Caching	💾	In-memory caching for performance
Docker Support	🐳	Run anywhere without local setup
Package Structure	📦	Clean, importable Python package
API Ready	🚀	Easy to plug into Django / FastAPI

---

📦 Platforms Generated

• ✅ TMDB
• ✅ IMDb
• ✅ Rotten Tomatoes (validated)
• ✅ Metacritic
• ✅ Letterboxd (movies only)
• ✅ JustWatch (PK region)

---

🗂️ Project Structure

linkify-media/
├── linkify_media/
│   ├── __init__.py       # Package entry point
│   ├── utils.py          # slugify, fetch helpers
│   ├── core.py           # TMDB logic + link generation
│   └── cli.py            # argparse CLI
├── assets/
├── .dockerignore
├── .env                  # TMDB_API_KEY (never commit this)
├── .gitignore
├── docker-compose.yml
├── Dockerfile
├── LICENSE
├── README.md
├── requirements.txt
└── pyproject.toml

---

🚀 Installation & Setup

Option A — Local (Python)

1. Clone Repository

git clone https://github.com/Abdullahkhan000/Linkify-Media
cd Linkify-Media

2. Create Virtual Environment

# Windows
python -m venv .venv
.venv\Scripts\activate

# Mac / Linux
python3 -m venv .venv
source .venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt
pip install .

4. Configure API Key

Create .env in project root:

TMDB_API_KEY=your_actual_api_key_here

⚠️ Never commit .env — it's already in .gitignore

Get your free API key at themoviedb.org/settings/api

---

Option B — Docker 🐳

No Python setup needed. Just Docker + your API key.

1. Clone & create .env

git clone https://github.com/Abdullahkhan000/Linkify-Media
cd Linkify-Media
echo TMDB_API_KEY=your_key_here > .env

2. Build image

docker build -t linkify-media .

3. Run

# Movie
docker run --env-file .env linkify-media "Inception" --media movie

# TV Show
docker run --env-file .env linkify-media "The Bear" --media tv

# Save JSON output
docker run --env-file .env -v ${PWD}/output:/app/output linkify-media "Dune" --json

💡 Windows PowerShell users: use ${PWD} not $(pwd) for volume mounts

---

🖥️ Usage (CLI)

# Movie (default)
linkify-media "Inception"

# TV Series
linkify-media "Breaking Bad" --media tv

# Save output as JSON file
linkify-media "Dune" --media movie --json

---

📤 Sample Output

{
    "Official Title": "Inception",
    "Release Year": "2010",
    "Genres": ["Action", "Science Fiction", "Adventure"],
    "Runtime (mins)": 148,
    "TMDB Rating": "8.369 (38000 votes)",
    "Poster URL": "https://image.tmdb.org/t/p/w500/oYuLEt3zVCKq57qu2F8dT7NIa6f.jpg",
    "Top Cast": ["Leonardo DiCaprio", "Joseph Gordon-Levitt", "Elliot Page", "Tom Hardy", "Ken Watanabe"],
    "TMDB Link": "https://www.themoviedb.org/movie/27205",
    "IMDb Link": "https://www.imdb.com/title/tt1375666/",
    "Rotten Tomatoes": "https://www.rottentomatoes.com/m/inception",
    "Metacritic": "https://www.metacritic.com/search/movie/inception/results",
    "Letterboxd": "https://letterboxd.com/film/inception/",
    "JustWatch (PK)": "https://www.justwatch.com/pk/search?q=Inception"
}

---

🧠 Architecture

linkify_media/
│
├── utils.py
│   ├── slugify()          # Clean URL-safe slugs
│   ├── fetch_json()       # Async GET requests
│   └── head_exists()      # URL validation (RT check)
│
├── core.py
│   ├── fetch_tmdb_data()  # Async TMDB search + details + credits
│   ├── generate_links()   # Platform links + RT validation + caching
│   └── CACHE              # In-memory cache dict
│
└── cli.py
    └── main()             # argparse CLI entrypoint

---

🧩 Use Cases

• Backend Movie APIs
• Django REST integration
• FastAPI async endpoints
• Media dashboards
• Streaming aggregation tools
• Data scraping & enrichment pipelines

---

🔜 Roadmap

• Async engine
• Docker support
• Python package structure
• PyPI release
• Redis caching
• Batch processing mode
• FastAPI version
• Trailer support (YouTube API)

---

🤝 Contributing

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

---

❤️ Support the Project

If this project saves you time or helps your workflow, consider supporting its development.

Your support helps add new features, improve performance, and maintain long-term updates.

---

📄 License

Licensed under the MIT License — free to use, modify, and distribute.

---

⭐ Star the repo if you find it useful!

🚀 Proudly made by code2encoder aka Shadow Dev 🚀