diff --git a/README.md b/README.md
index 0f16dc4..c25a624 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,105 @@
-# musicfetch
+# 🎵 MusicFetch
 
-A Python script to grab music from Lidarr/YT-DL using an artist name / youtube link
\ No newline at end of file
+**MusicFetch** is a smart command-line utility that fetches music by querying Lidarr (a music collection manager) or, if no match is found or a timeout occurs, falls back to downloading using `yt-dlp`. It supports input in the form of either:
+
+- `"Artist - Track"` (e.g. `"Daft Punk - Harder Better Faster Stronger"`)
+- A full YouTube URL (e.g. `"https://www.youtube.com/watch?v=dQw4w9WgXcQ"`)
+
+The downloaded track is organized into your Lidarr media folder or a YouTube subfolder if it's a fallback.
+
+---
+
+## 🚀 Features
+
+- Searches for and adds artists to Lidarr.
+- Automatically triggers album searches in Lidarr.
+- Falls back to downloading via `yt-dlp` if no match is found.
+- Supports metadata extraction from YouTube URLs.
+- Handles Lidarr timeouts gracefully.
+
+---
+
+## 📦 Dependencies & Installation
+
+### 🐍 Python Dependencies
+
+- Python 3.6+
+- `requests`
+
+You can install the required Python packages using:
+
+```bash
+pip install requests
+
+📼 External Tools
+
+    yt-dlp: YouTube downloader for audio/video.
+
+Install via pip (recommended):
+
+pip install -U yt-dlp
+
+Or install system-wide:
+
+sudo apt install yt-dlp  # On Debian/Ubuntu
+
+⚙️ Configuration
+
+    Lidarr Setup
+
+        Ensure Lidarr is running and accessible (e.g., http://localhost:8686).
+
+        Create or retrieve your API key from Lidarr's settings.
+
+    Environment Variable
+    Set your API key in the terminal session:
+
+export LIDARR_API_KEY="your-lidarr-api-key"
+
+Or run inline:
+
+    LIDARR_API_KEY="your-lidarr-api-key" ./musicfetch.py "Artist - Track"
+
+🧑‍💻 Usage
+🔉 Download by Search Term
+
+./musicfetch.py "Artist - Track"
+
+Example:
+
+./musicfetch.py "ODESZA - Bloom"
+
+If Lidarr finds the artist and album, it will trigger a download in Lidarr. If not, the song will be downloaded via yt-dlp using a YouTube search.
+📺 Download by URL
+
+./musicfetch.py "https://www.youtube.com/watch?v=xxxxxxxxxxx"
+
+The script extracts metadata from the video and organizes the file under the artist's folder.
+📁 Output Structure
+
+Music is saved in:
+
+/media/music/
+├── Artist Name/
+│   ├── Album Name/   (if found via Lidarr)
+│   └── youtube/      (if fallback used)
+
+❓ Troubleshooting
+
+    No results from Lidarr?
+    Make sure your Lidarr installation is reachable and the artist exists or can be found in metadata sources.
+
+    yt-dlp errors?
+    Try updating it:
+
+    yt-dlp -U
+
+    Permission denied or file not found?
+    Ensure /media/music exists and is writable.
+
+🛠️ Contributing
+
+PRs welcome! Just keep it simple and compatible with Bash-based workflows.
+📜 License
+
+MIT – Use it freely and improve it as you wish!
\ No newline at end of file