Invidious Development Roadmap: Current Plans and Future Directions

The Invidious development roadmap is decentralized across GitHub issues, TODO comments in the Crystal codebase, and a future release placeholder in CHANGELOG.md, prioritizing companion service hardening, transcript system rewrites, API expansions, and deployment improvements.

Invidious is an open-source, privacy-focused frontend for YouTube written in Crystal and built on the Kemal web framework. Rather than maintaining a single formal roadmap document, the project uses a community-driven approach where upcoming features are tracked through the ## vX.Y.0 (future) section in CHANGELOG.md and approximately 64 TODO comments scattered throughout the source code. This decentralized planning method allows the maintainers to adapt quickly to YouTube API changes while continuously improving the self-hostable video platform.

Upcoming Features and Priorities

The most concrete signals of Invidious's future direction can be extracted from the changelog's future release section and inline code comments. The following areas represent the active development focus for the coming months.

YouTube Companion Integration

The Invidious Companion—an optional helper service that signs YouTube requests—is slated for significant hardening. Planned improvements include strengthening Content Security Policy (CSP) generation for companion endpoints, improving proxy handling, and making the companion fully optional in the configuration layer. The relevant configuration logic resides in src/invidious/config.cr between lines 70-88, where companion URLs and proxy settings are validated during application startup.

Transcript and Caption System Rewrite

The current transcript implementation is scheduled for a complete rewrite to become a first-class feature rather than a workaround. This refactor aims to improve reliability of caption extraction and provide better integration with the video player. The changelog explicitly notes this rewrite under the transcript section, indicating it is a priority for the next major release cycle.

API Stability and New Endpoints

The public REST API will receive several enhancements to improve consistency and functionality. Planned additions include a sort_by parameter for the /api/v1/channels/{id}/streams endpoint, exposure of the published field for related video objects, and standardized error object returns for parse failures. These endpoints are implemented in the src/invidious/routes/api/v1/ directory, with video-specific logic found in src/invidious/routes/api/v1/videos.cr.

User Interface Improvements

Several user-facing enhancements are in active development, including a dedicated search bar button, support for direct YouTube URL entry fields, alphabetical playlist sorting options, and keyboard shortcuts for caption styling. The frontend player logic lives in assets/js/player.js, which handles VideoJS configuration and caption rendering.

Configuration and Deployment Enhancements

Deployment flexibility is expanding with support for UNIX socket listeners alongside traditional TCP ports, making nginx integration more efficient. Docker builds are being optimized to compile OpenSSL from source for better cryptographic compatibility, and the tzdata dependency is being made optional to reduce container size. Configuration loading and validation occur in src/invidious/config.cr, which processes YAML files and environment variable overrides.

Code Quality and Maintenance

Internal refactoring efforts focus on moving top-level constants into dedicated modules to improve namespace hygiene and implementing stricter ameba linting across the entire Crystal codebase. Legacy proxy code is scheduled for replacement, and the TODO comments scattered throughout files like src/invidious.cr and src/invidious/yt_backend/extractors.cr serve as markers for ongoing technical debt reduction.

Internationalization Expansion

The project continues expanding language packs through Weblate integration, with translation files stored in the locales/ directory. This ongoing work ensures the interface remains accessible to non-English speakers as new UI components are added.

Architecture Overview

Understanding the file structure helps developers interpret the roadmap items in context. The application entry point at src/invidious.cr bootstraps the Kemal web server, loads configuration from src/invidious/config.cr, and registers routes defined in src/invidious/routes/. YouTube data extraction logic lives in src/invidious/yt_backend/extractors.cr, which implements multiple client strategies (WEB, TVHTML5) for resilient video metadata retrieval. Database models for PostgreSQL tables—handling channels, videos, subscriptions, and notifications—are organized under src/invidious/database/.

Development Environment Setup

Developers interested in contributing to the roadmap items can set up a local instance using the following steps.

Running Invidious Locally (Crystal ≥ 1.12)

Clone the repository and install dependencies:

# Clone the repo

git clone https://github.com/iv-org/invidious.git
cd invidious

# Install Crystal dependencies

shards install

# Create a minimal config (copy the example and fill the HMAC key)

cp config/config.example.yml config/config.yml
sed -i 's/HMAC_KEY: ""/HMAC_KEY: "your-32-char-secret"/' config/config.yml

# Start the server

crystal run src/invidious.cr

The server reads config/config.yml by default, with the loader implemented in src/invidious/config.cr between lines 98-106.

Querying the Public API

Test API endpoints against a live instance:

# Get video metadata (replace <VIDEO_ID> with a YouTube ID)

curl https://invidious.snopyta.org/api/v1/videos/<VIDEO_ID>

This endpoint is implemented in src/invidious/routes/api/v1/videos.cr.

Adding a Custom Route

To extend the API, create a new file in the routes directory:

# src/invidious/routes/api/v1/hello.cr

module Invidious::Routes::API::V1
  get "/hello/:name" do |env|
    name = env.params.url["name"]
    {message: "Hello, #{name}!"}.to_json
  end
end

Register the file in src/invidious/routes/api/v1.cr:

require "./hello"

# other requires...

New routes follow the pattern established throughout the routes/api/v1 folder.

Configuring the Companion Service

Programmatically configure the companion in your development environment:

# Assume you have a running companion at http://companion.local

companion = Invidious::Config::CompanionConfig.new
companion.private_url = URI.parse("http://companion.local")
companion.public_url  = URI.parse("/companion")
companion.builtin_proxy = false

# Add to the main config

config.invidious_companion << companion

The companion handling code is defined in src/invidious/config.cr at lines 70-88.

Summary

• The Invidious development roadmap is decentralized, relying on CHANGELOG.md, TODO comments, and GitHub issues rather than a formal document.
• Key upcoming features include transcript system rewrites, companion service hardening, API endpoint expansions, and UNIX socket support.
• Code quality initiatives involve ameba linting enforcement, module reorganization, and legacy proxy code replacement.
• Architecture follows a layered Crystal/Kemal structure with clear separation between YouTube extraction logic, database models, and API routes.
• Contributors should monitor the ## vX.Y.0 (future) section in CHANGELOG.md and the TODO comment inventory for the latest priority items.

Frequently Asked Questions

Where is the official Invidious development roadmap documented?

Invidious does not maintain a standalone roadmap file. Instead, upcoming features are tracked through the ## vX.Y.0 (future) placeholder in CHANGELOG.md, approximately 64 TODO comments embedded in the source code, and active GitHub issues. This distributed approach allows the project to remain agile and responsive to YouTube's frequent API changes.

What are the next major features planned for Invidious?

According to the changelog and source analysis, priority areas include a complete rewrite of the transcript system to make it a first-class feature, hardening the optional Invidious Companion service for better CSP and proxy handling, adding sort_by parameters to channel stream endpoints, and implementing UNIX socket listener support for improved deployment flexibility.

How is the Invidious codebase organized?

The Crystal application uses a layered architecture: src/invidious.cr serves as the entry point that bootstraps Kemal and loads configuration from src/invidious/config.cr. YouTube data extraction logic resides in src/invidious/yt_backend/extractors.cr, API endpoints are grouped under src/invidious/routes/api/v1/, and PostgreSQL database models are located in src/invidious/database/. Frontend assets including the VideoJS player configuration are stored in assets/js/.

How can developers contribute to the Invidious roadmap?

Developers can participate by reviewing items marked with TODO comments in the codebase, checking the "future" section of CHANGELOG.md for planned version goals, and submitting pull requests addressing open issues. Setting up a local development environment requires Crystal ≥ 1.12, PostgreSQL, and running shards install to fetch dependencies. Contributions should follow the ameba linting standards and include appropriate tests for new API endpoints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}