FilmBox is a collaborative movie discovery application that helps groups of friends find the perfect movie to watch together. Users can create or join rooms, swipe through movie recommendations together, and discover films that everyone in the group likes.
- Create private rooms with shareable room IDs
- Join existing rooms using room codes
- Real-time user management with Socket.IO
- Host controls for starting sessions
- Integration with The Movie Database (TMDB) API
- 20 curated movies per session from popular films
- Rich movie information including posters, genres, descriptions, and ratings
- German language support (de-DE)
- Tinder-style swipe interface for movie selection
- Like/dislike voting with keyboard shortcuts
- Real-time vote synchronization across all users
- Progress tracking for each user
- Algorithm to find movies liked by ALL users in the room
- Beautiful results display with matched films
- Host-controlled session restart functionality
- Responsive design with glassmorphism effects
- Beautiful gradient backgrounds
- Smooth animations and transitions
- Mobile-friendly interface
- Keyboard navigation support
- Node.js 18+
- NPM or Yarn
- TMDB API Key (free from themoviedb.org)
-
Clone the repository:
git clone https://github.com/mikaolmes/FilmBox.git cd FilmBox -
Install dependencies:
npm install
-
Set up environment variables: Create a
.env.localfile in the root directory:NEXT_PUBLIC_TMDB_API_KEY=your_tmdb_api_key_here
-
Start the development server:
npm run dev
-
Open your browser: Visit http://localhost:3000
- Set your username (optional, auto-generated if empty)
- Choose to create a new room or join an existing one
- Host: Create a room and share the generated room ID
- Guests: Join using a room ID
- Wait for all participants to join
- Host starts the session when ready
- All users see the same 20 movies in randomized order
- Vote on each movie: 👍 (Like) or 👎 (Dislike)
- Wait for all users to complete their voting
- View movies that ALL users liked
- Host can start a new session with fresh movies
←(Left Arrow): Dislike current movie→(Right Arrow): Like current movie↓(Down Arrow): Toggle movie descriptionSpaceorEnter: Like movie (during voting) / Restart session (on results, host only)
- Next.js 14 - React framework with App Router
- TypeScript - Type safety and better development experience
- Tailwind CSS - Utility-first CSS framework
- React Hooks - Modern state management
- Socket.IO - Real-time bidirectional communication
- Next.js API Routes - Serverless backend functions
- In-memory data storage - Room and vote management
- TMDB (The Movie Database) - Movie data, posters, and metadata
- ESLint - Code linting
- PostCSS - CSS processing
- TypeScript - Static type checking
| Variable | Description | Required |
|---|---|---|
NEXT_PUBLIC_TMDB_API_KEY |
Your TMDB API key for fetching movie data | ✅ Yes |
- Visit TMDB
- Create a free account
- Go to Settings → API
- Request an API key (choose "Developer" option)
- Copy your API key to
.env.local
This project is open source and available under the MIT License.
- The Movie Database (TMDB) for providing the movie API
- Next.js for the amazing React framework
- Socket.IO for real-time communication
- Tailwind CSS for the styling system
Made with ❤️ for movie lovers who can't decide what to watch!