SoundCloud Playlist Manager 🎵

A modern web application that helps you organize your SoundCloud liked tracks into smart playlists with AI-powered suggestions, featuring a gamified Tinder-style interface and seamless drag-and-drop functionality.

✨ Features

• 🔐 Secure OAuth 2.1 Authentication - PKCE-based SoundCloud login with encrypted session storage
• 🎴 Tinder-Style Categorization - Swipe through your tracks in a fun, gamified interface
• 🎯 Smart Suggestions - Automatic playlist buckets based on genre, BPM, artist, and tags
• 🎨 Drag & Drop Editor - Effortlessly reorder tracks and move them between playlists
• ☁️ One-Click Sync - Create and update playlists directly on SoundCloud
• 🎭 Beautiful UI/UX - Modern design with glassmorphism effects and smooth animations
• 📱 Fully Responsive - Optimized for both desktop and mobile devices

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm/yarn/pnpm
• A SoundCloud Developer account and registered app

1. Clone the Repository

git clone <your-repo-url>
cd my-soundcloud

2. Install Dependencies

npm install
# or
yarn install
# or
pnpm install

3. Set Up SoundCloud App

1. Go to SoundCloud Developers
2. Create a new app or use an existing one
3. Set the redirect URI to: http://localhost:3000/api/auth/soundcloud/callback
4. Note your Client ID and Client Secret

4. Configure Environment Variables

Create a .env.local file in the root directory:

SOUNDCLOUD_CLIENT_ID=your_client_id_here
SOUNDCLOUD_CLIENT_SECRET=your_client_secret_here
SESSION_SECRET=your_random_32_character_secret_here
NEXTAUTH_URL=http://localhost:3000

Generate a secure SESSION_SECRET:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

5. Run the Development Server

npm run dev
# or
yarn dev
# or
pnpm dev

Open http://localhost:3000 in your browser.

📦 Project Structure

my-soundcloud/
├── app/
│   ├── api/
│   │   ├── auth/
│   │   │   ├── soundcloud/        # OAuth endpoints
│   │   │   ├── refresh/           # Token refresh
│   │   │   ├── logout/            # Logout endpoint
│   │   │   └── me/                # Get session
│   │   └── soundcloud/
│   │       ├── likes/             # Fetch liked tracks
│   │       └── playlists/         # Playlist CRUD
│   ├── dashboard/                 # Main dashboard
│   ├── categorize/                # Tinder-style interface
│   ├── playlists/                 # Playlist editor
│   ├── layout.tsx                 # Root layout
│   ├── page.tsx                   # Landing page
│   └── globals.css                # Global styles
├── components/
│   ├── Navbar.tsx                 # Navigation bar
│   ├── SwipeCard.tsx              # Swipe card component
│   ├── BucketGrid.tsx             # Bucket selection grid
│   ├── PlaylistCard.tsx           # Playlist card with editor
│   ├── SortableTrackList.tsx      # Drag & drop track list
│   └── SortableTrackItem.tsx      # Individual track item
├── lib/
│   ├── pkce.ts                    # PKCE utilities
│   ├── auth.ts                    # Session management
│   ├── soundcloud.ts              # SoundCloud API client
│   └── matching.ts                # Playlist matching algorithm
└── public/                        # Static assets

🎯 How It Works

1. Authentication Flow

• User clicks "Connect with SoundCloud"
• App generates PKCE code verifier and challenge
• User authorizes on SoundCloud
• App exchanges code for access token
• Token stored in encrypted session cookie

2. Smart Categorization

The app analyzes your liked tracks and creates buckets based on:

• Genre - Groups tracks by their primary genre
• BPM Ranges - Creates tempo-based playlists (90-110, 110-130, etc.)
• Artist - Collects multiple tracks from the same artist
• Tags - Identifies popular tags and creates themed playlists

3. Swipe Interface

• Swipe right (or click a bucket) to add track to playlist
• Swipe left to skip
• Progress bar shows categorization status
• Real-time stats display

4. Playlist Management

• Drag tracks to reorder within playlists
• Edit playlist names and descriptions
• Remove unwanted tracks
• Sync to SoundCloud with one click

🛠️ Tech Stack

• Framework: Next.js 14 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• Animations: Framer Motion
• Drag & Drop: @dnd-kit
• Session: iron-session
• Notifications: react-hot-toast
• Deployment: Vercel

🌐 Deployment to Vercel

1. Push to GitHub

git add .
git commit -m "Initial commit"
git push origin main

2. Deploy to Vercel

1. Go to vercel.com
2. Import your GitHub repository
3. Configure environment variables:
   • SOUNDCLOUD_CLIENT_ID
   • SOUNDCLOUD_CLIENT_SECRET
   • SESSION_SECRET
   • NEXTAUTH_URL (set to your production URL)
4. Deploy!

3. Update SoundCloud App Settings

After deployment, add your production URL to the SoundCloud app's redirect URIs:

• https://your-domain.vercel.app/api/auth/soundcloud/callback

🎨 Customization

Tailwind Theme

Edit tailwind.config.ts to customize colors, animations, and more:

theme: {
  extend: {
    colors: {
      soundcloud: {
        orange: '#ff5500',
        dark: '#111',
        gray: '#333',
      },
    },
  },
}

Matching Algorithm

Adjust the matching algorithm in lib/matching.ts:

• Minimum tracks per bucket
• BPM range sizes
• Tag popularity threshold
• Genre filtering

🐛 Troubleshooting

"Not authenticated" errors

• Check that environment variables are set correctly
• Clear browser cookies and try again
• Ensure SESSION_SECRET is at least 32 characters

Token expired errors

• The app should auto-refresh tokens
• Check /api/auth/refresh endpoint
• Verify refresh token is stored in session

Tracks not loading

• Check browser console for API errors
• Verify SoundCloud API is accessible
• Ensure you have liked tracks on your account

📝 API Rate Limits

SoundCloud API has rate limits. The app handles pagination automatically, but be aware:

• Max 200 items per request
• Rate limits apply per client
• Refresh tokens to maintain access

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

• SoundCloud API
• Next.js
• dnd-kit
• Framer Motion

📧 Support

If you have any questions or need help, please open an issue on GitHub.

---

Made with ❤️ and 🎵