TunedFeed

Taste-trained video discovery

A dark, red, signal-driven recommendation lab for training a personal YouTube-style feed with swipes, saves, skips, blocks, and manual preference controls.

---

Why TunedFeed?

Most recommendation systems feel opaque: you click once and the feed decides who you are. TunedFeed flips that relationship. It gives you a visible training cockpit where every swipe, save, skipped card, hidden tag, and manual preference immediately reshapes your profile.

TunedFeed is built as a professional Next.js application with a polished dark-red interface, local-first taste state, optional YouTube Data API integration, and a transparent recommendation pipeline that is easy to inspect, extend, and contribute to.

Highlights

• Swipe-based training — like, dislike, skip, or save videos in a Tinder-style deck.
• Live taste profile — categories, tags, creators, and signal counts update in real time.
• Manual controls — boost categories and tags, hide unwanted tags, and tune the feed without waiting for the algorithm.
• Seed from YouTube links — paste a public YouTube URL and add it as a positive signal.
• Separate For You page — recommendations are generated from your taste profile, not just recycled liked videos.
• Multi-signal ranking — sort recommendations by algorithmic match, views, likes, and subscriber count.
• Optional real YouTube data — use YOUTUBE_API_KEY for live discovery, with mock fallback data for local development.
• Local-first privacy — training state is stored in the browser via localStorage.
• Modern stack — Next.js App Router, React 19, TypeScript, Tailwind CSS v4, and Turbopack.

Product flow

flowchart LR
  A[Swipe or seed videos] --> B[Update local taste profile]
  B --> C[Build search query]
  C --> D[Fetch YouTube or fallback catalog]
  D --> E[Rank by profile + feature signals]
  E --> F[For You recommendations]
  F --> A

Loading

Tech stack

Layer	Choice
Framework	Next.js 16 App Router
UI	React 19 + TypeScript
Styling	Tailwind CSS v4 + custom dark/red design tokens
State	useSyncExternalStore + browser localStorage
Data	YouTube Data API v3 with local fallback catalogs
Ranking	Profile weights + feature-based recommendation scoring
Tooling	ESLint, TypeScript, Turbopack

Getting started

Prerequisites

• Node.js 20.9 or newer
• npm
• Optional: a YouTube Data API v3 key for live video discovery

Installation

git clone https://github.com/byalex33/tunedfeed.git
cd tunedfeed
npm install

Optional environment variables

Create .env.local if you want live YouTube results:

YOUTUBE_API_KEY=your_youtube_data_api_key

Without a key, TunedFeed runs fully with built-in demo training and discovery catalogs.

Run locally

npm run dev

Open http://localhost:3000.

Available scripts

Command	Description
npm run dev	Start the development server
npm run build	Create a production build
npm run start	Start the production server
npm run lint	Run ESLint

Project structure

app/
  api/
    recommendations/    # For You search endpoint
    training/           # Training batch endpoint
    videos/lookup/      # YouTube URL import endpoint
  for-you/              # Personalized recommendation page
  train/                # Swipe training page
  globals.css           # Design tokens and global styling
components/
  tunedfeed/            # Product-specific interface components
  ui/                   # Reusable UI primitives
lib/
  features.ts           # Feature vector learning helpers
  recommendations.ts    # Profile scoring and ranking logic
  videos.ts             # Demo catalogs and video types
  youtube.ts            # YouTube Data API integration

How recommendations work

1. Training signals are weighted

   • Like and save increase category, tag, and creator affinity.
   • Skip is a light negative signal.
   • Dislike strongly reduces similar content.

2. Manual preferences override drift

   • Favorite categories and tags can be boosted directly.
   • Hidden tags are filtered out of both training and recommendations.

3. A search query is generated

   • TunedFeed builds a YouTube query from the strongest positive category and tag signals.

4. Candidates are ranked

   • Candidate videos are scored by profile fit.
   • After enough ratings, feature-based scoring adds format and engagement similarity.

5. The loop keeps learning

   • Actions on the For You page feed back into the same profile.

API routes

Route	Method	Purpose
/api/training	GET	Fetch an initial training catalog
/api/training	POST	Fetch the next profile-aware training batch
/api/recommendations	GET	Fetch recommendation candidates for a profile query
/api/videos/lookup	POST	Import metadata for a pasted YouTube link

Privacy model

TunedFeed is intentionally local-first:

• Taste profile state is stored in your browser.
• The server only uses the YouTube API key for API requests.
• Demo mode requires no external API key.
• Clearing site data resets the trained profile.

Contributing

Contributions are welcome, but all contributors must follow the project rules in CONTRIBUTING.md before opening a pull request.

License

TunedFeed is released under the MIT License.

---

Built for people who want feeds they can actually steer.