diff --git a/README.md b/README.md
new file mode 100644
index 0000000..eaf0b1c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,199 @@
+# Relationships Jukebox
+
+**Relationships Jukebox** is a lightweight World of Warcraft music addon that lets you play your own local audio files in-game through a full playlist window, a compact mini player, and simple slash commands.
+
+The addon scans a local `Media` folder, builds a playlist automatically, and lets you search, play, shuffle, skip, stop, and manage tracks without leaving the game.
+
+## Features
+
+- Supports **MP3**, **WAV**, and **OGG** files
+- Full in-game playlist browser with paged track list
+- **Search** box for quickly filtering tracks
+- **Play**, **Play All**, **Shuffle**, **Skip**, **Previous**, and **Stop** controls
+- Compact **Mini Player** for use during gameplay
+- **Minimap button**
+  - **Left-click:** Toggle Mini Player
+  - **Right-click:** Toggle Full GUI
+- Automatically imports tracks from `AutoPlaylist.lua`
+- Stores track names and durations for smoother autoplay and shuffle playback
+- Attempts to improve **WoW 1.12 MP3 compatibility** by sanitizing problematic MP3 files during playlist generation
+- Works even without metadata by falling back to estimated durations
+
+
+## Installation
+
+1. Extract the addon into your WoW `Interface\AddOns` folder.
+2. Make sure the folder name is exactly:
+
+   ```text
+   RelationshipsJukeBox
+   ```
+
+3. Place your music files inside:
+
+   ```text
+   Interface\AddOns\RelationshipsJukeBox\Media
+   ```
+
+4. Run:
+
+   ```text
+   GeneratePlaylist.bat
+   ```
+
+5. Start or reload the game:
+
+   ```text
+   /reload
+   ```
+
+## Supported Formats
+
+The addon scans the `Media` folder recursively for:
+
+- `.mp3`
+- `.wav`
+- `.ogg`
+
+## How Playlist Generation Works
+
+The addon does not scan the `Media` folder directly in-game. Instead, it uses a generated file named:
+
+```text
+AutoPlaylist.lua
+```
+
+`GeneratePlaylist.bat` launches the PowerShell generator, which:
+
+- scans the `Media` folder for supported audio files
+- creates or updates `AutoPlaylist.lua`
+- captures track names
+- tries to determine durations
+- checks MP3 files for WoW 1.12 compatibility issues
+- optionally uses `ffmpeg` / `ffprobe` for better metadata and MP3 sanitization
+
+After generating the playlist, use `/reload` so the addon can import the updated track list.
+
+## ffmpeg / 7-Zip / WinRAR Notes
+
+The playlist generator is designed to be friendly on Windows:
+
+- If `ffmpeg` and `ffprobe` are already installed, it will use them
+- If not, the script can attempt to **auto-download ffmpeg** into a local `ffmpeg` folder inside the addon
+- If `.7z` extraction is needed, it can use **7-Zip** or **WinRAR**
+- You can run the batch file with:
+
+  ```text
+  GeneratePlaylist.bat -UseWinRAR
+  ```
+
+  to prefer WinRAR for archive extraction
+
+If ffmpeg is unavailable, the generator can still build a playlist using estimated durations, but some MP3 files may not play correctly in WoW 1.12.
+
+## In-Game Controls
+
+### Main Window
+
+The main window includes:
+
+- search field
+- Search / Clear buttons
+- per-track Play and Remove buttons
+- playback controls for playlist mode
+- page navigation
+- status messages
+
+### Mini Player
+
+The mini player provides quick access to:
+
+- Previous
+- Stop
+- Next
+- Open full GUI
+- current track display
+
+### Minimap Button
+
+- **Left-click:** Toggle Mini Player
+- **Right-click:** Toggle Full GUI
+
+## Slash Commands
+
+```text
+/rjukebox play
+/rjukebox shuffle
+/rjukebox stop
+/rjukebox skip
+/rjukebox prev
+/rjukebox pause
+/rjukebox mini
+```
+
+Short alias:
+
+```text
+/rj
+```
+
+## Typical Usage
+
+1. Put music into the `Media` folder
+2. Run `GeneratePlaylist.bat`
+3. Log in or type `/reload`
+4. Open the addon window
+5. Search for a song or press **Play All** / **Shuffle**
+6. Use the mini player while you play
+
+## Track Names
+
+The addon automatically cleans display names for the UI by removing things like:
+
+- leading track numbers
+- file extensions
+- extra underscores or separators
+
+This helps filenames display more like song titles in the playlist.
+
+## Remove Button Behavior
+
+The **Remove** button removes a track from the addon's saved playlist database.
+
+Important: if the audio file still exists in the `Media` folder and is still included in `AutoPlaylist.lua`, it can be imported again the next time you regenerate the playlist or reload the addon.
+
+## Troubleshooting
+
+### No tracks appear in-game
+
+- Confirm your files are inside `RelationshipsJukeBox\Media`
+- Run `GeneratePlaylist.bat`
+- Make sure `AutoPlaylist.lua` was created
+- Use `/reload`
+
+### Some MP3s do not play
+
+WoW 1.12 can be picky about MP3 encoding. Re-run the generator and let it sanitize files if `ffmpeg` is available.
+
+### Durations seem wrong
+
+If metadata cannot be read, the generator falls back to estimated/default durations.
+Installing ffmpeg improves duration detection.
+
+### The generator cannot extract ffmpeg
+
+Install one of the following:
+
+- **7-Zip**
+- **WinRAR**
+- or manually place `ffmpeg.exe` and `ffprobe.exe` in:
+
+  ```text
+  RelationshipsJukeBox\ffmpeg
+  ```
+
+## Credits
+
+Author: **Relationship**
+
+If you package releases, consider including this README alongside the addon so users know to place tracks in `Media`, run the generator, and reload the UI.