CTR ranking engine

Most tube sites order videos by upload date or raw view count. Both reward the wrong thing: recency favours whatever was added last, and views favour whatever has been online longest. The CTR Ranking plugin replaces that with a true engagement engine, so the videos your visitors actually click and watch rise to the top.

It is an optional plugin (version 3) that ships with TubePress. Activate it from /admin/plugins and tune it on its own page at /admin/ctr.

What CTR ranking is

CTR stands for click-through rate — the share of people who, having seen a thumbnail, choose to click it. Ranking by CTR measures attractiveness and engagement rather than age. The plugin records three real signals on the client:

• Impressions — every thumbnail genuinely scrolled into view (via an IntersectionObserver), weighted by its position.
• Clicks — each click on a video, category, performer or channel card.
• Watch-completion — how far the player actually gets through a video, at the 25%, 50%, 75% and 100% milestones.

The V3 engine

Scores are recomputed on a schedule and combine four multipliers:

ranking_score = quality x retention x freshness x fatigue

• Quality is a position- and surface-debiased click-through rate (COEC — clicks over expected clicks). Expected clicks accrue at impression time from a per-context, per-position prior, so a card in slot one must beat the average slot-one click rate to rise. Position bias is cancelled mathematically rather than guessed at.
• Retention rewards videos people finish. The 25/50/75/100% completion data lifts content that holds viewers and demotes click-bait that bounces early.
• Freshness gives new uploads a temporary boost (by default up to roughly 3x in the first hours, fading back to neutral within two weeks) so good new content gets discovered.
• Fatigue gently rests videos that have already been shown heavily on the homepage, keeping the rotation varied.

The quality multiplier is capped, and all of these weights are adjustable in the advanced settings if you want to lean harder on watch-time, freshness or click-rate.

Entity ranking

Engagement tracking is not limited to videos. Category, performer (pornstar) and channel cards are tracked too, and the ones visitors click into most surface first in Trending listings. Each entity's listing score is derived from the engagement of its published videos, and its display thumbnail becomes the best-performing video it contains — so your most clickable artwork does the work of pulling visitors deeper into the site.

Built-in anti-spam

Because the score decides ranking, it is defended against manipulation out of the box:

• Bots and headless browsers are excluded from every signal.
• Each click, completion and entity-click counts at most once per IP, per target, per hour (completions count once per quartile), so a single visitor cannot vote a video up.
• Only real, published videos are ever tracked — drafts and fake IDs are rejected.
• The quality multiplier is capped, limiting how far any one video can be pushed.
• Every tracking beacon is HMAC-signed with a server secret and a daily-rolling token, so requests cannot be forged.

The homepage rotation pool

To stop the front page looking identical all day, the plugin builds a rotation pool of 24 groups drawn from your top-ranked, well-tested videos. The homepage advances through one group every 30 minutes, so the top of the site feels fresh throughout the day while still showing genuinely high-engagement content. You can switch the pool off if you prefer a static ranked feed.

Enabling & tuning

After activating the plugin, open /admin/ctr. The page shows live stats — videos ranked, impressions, clicks and average watch completion — and a Recalculate now button.

1. Pick a strategy. One click on a preset — Balanced, Fresh & Discovery, Most Watched or Trending Now — sets every weight for you.
2. Toggle the features. Enable engagement tracking, watch-completion, entity ranking, the rotation pool and bot filtering independently.
3. Fine-tune if you wish. The advanced panel exposes the recalculation frequency, quality cap, freshness boost, retention clamp, fatigue softness and more. Editing any value switches the strategy to Custom.

The master switch is ctr_enabled. When it is off, the whole site falls back to view-count and recency ordering, so you can disable ranking instantly without uninstalling anything.

Built for scale

The engine is engineered for catalogues with millions of videos. Tracking is written as single batched upserts; recalculation is chunked by ID range and only writes rows whose score actually changed; and there is no cache layer to invalidate. Scores rebuild on a self-contained schedule (configurable from every 5 minutes to every 12 hours) using the built-in pseudo-cron, so no server crontab is required. Everything — the database schema, tracking endpoints, recalculation job, sort wiring and admin page — is provided by the plugin; nothing is bolted onto the base CMS.

Next steps