Overview

Relevant source files

• README.md

Purpose and Scope

This document provides a high-level introduction to ytify, a privacy-first audio streaming platform built for efficient, ethical media consumption. It covers the project's core philosophy, architectural design, technology stack, and deployment strategy. For detailed technical implementation of the architecture, see Architecture Overview. For setup instructions, see Installation and Setup.

What is ytify?

ytify is a Progressive Web App (PWA) that streams audio content from YouTube and YouTube Music with a focus on:

• Performance: Optimized for low-bandwidth networks and minimal buffering
• Privacy: All personalization happens on-device with no server-side tracking
• Efficiency: Lean resource usage and intentional design choices
• Control: User-centric features without information overload

The project originated in January 2022 as a response to NewPipe's streaming failures under poor network conditions. It has evolved into a comprehensive audio platform that prioritizes robust performance and user autonomy.

Sources: README.md10-16

Core Capabilities

Feature	Description
Audio Streaming	YouTube/YT Music audio with adaptive quality selection (worst/low/medium/high)
Queue Management	Manual ordering, shuffle modes, contextual auto-fill with related content
Collections	User-created playlists with cloud sync support
Radio Mode	Continuous playback via on-device recommendation engine
Synced Lyrics	Time-synchronized lyrics via LRCLIB integration
Video Playback	Optional video mode with quality/codec selection (AV1/VP9/AVC)
Library System	History tracking, favorites, listen later, channel subscriptions
Hub/Discovery	Personalized feeds (subfeed, gallery, frequently played)
Dynamic Theming	UI adapts colors based on current artwork
Audio Downloads	Offline playback support
PWA Features	Installable app, share targets, offline capabilities

Sources: README.md18-30

High-Level Architecture

Diagram: Overall System Architecture with Code Entities

The architecture implements a JAMstack pattern with serverless backend:

Layer	Components	Key Files
Presentation	SolidJS components	src/components/Player.tsx src/components/Queue.tsx src/components/Library.tsx src/components/Hub.tsx
State	Reactive stores	src/stores/playerStore.ts src/stores/queueStore.ts src/stores/store.ts
Business Logic	Core utilities	src/lib/player.ts src/lib/cloudSync.ts src/lib/library.ts src/lib/helpers.ts
Edge Functions	Netlify Edge	netlify/edge-functions/fallback.ts netlify/edge-functions/sync.ts netlify/edge-functions/s.ts
API Functions	Vercel Serverless	api/find.ts api/album.ts
Persistence	Browser localStorage	config, drawer, library_*, dbsync_* keys
External APIs	Third-party services	Invidious, RapidAPI, LRCLIB, JioSaavn

Sources: index.html1-40 README.md1-93 src/index.tsx netlify/edge-functions/ api/

Technology Stack

Frontend Technologies

Component	Technology	Purpose
UI Framework	Solid.js	Reactive rendering without virtual DOM
Build Tool	Vite	Development server, HMR, bundling
Language	TypeScript	Type-safe development
CSS Framework	Open Props	Design tokens and utilities
PWA Plugin	vite-plugin-pwa	Service worker, manifest generation
Icons	Remix Icons	UI iconography

Backend Technologies

Component	Technology	Purpose
Edge Runtime	Netlify Edge Functions	Stream proxying, link previews, sync
Serverless API	Vercel Functions	JioSaavn integration
Cloud Storage	Netlify Blobs	Library synchronization
Data Format	JSON	Configuration and library storage

External Integrations

Service	Purpose
Invidious	YouTube data API and stream proxy
RapidAPI	Fallback stream provider for Topic artists
JioSaavn	Indian music streaming alternative
LRCLIB	Synchronized lyrics provider

Sources: README.md86-92

Application Entry Flow

Diagram: Bootstrap Sequence with Code Entities

The application bootstrap follows this sequence:

1. HTML Entry: index.html1-40 serves as the PWA entry point

   • Lines 7-24: Meta tags for SEO, Open Graph, and PWA manifest
   • Lines 27-30: Icon definitions for various platforms
   • Line 37: Module script tag loading src/index.tsx

2. Module Initialization: src/index.tsx executes

   • Imports render() from solid-js/web
   • Imports root App component
   • Calls render(() => <App />, document.getElementById('root')!)

3. Store Hydration: Reactive stores read from localStorage

   • src/stores/playerStore.ts: Reads config for playback preferences
   • src/stores/queueStore.ts: Reads config for queue settings
   • src/stores/store.ts: Reads global app state
   • src/lib/config.ts: Manages config object persistence

4. Library Loading: Collection data loads asynchronously

   • library_meta: Collection timestamps and metadata
   • library_tracks: Track metadata cache
   • library_*: Individual collections (favorites, channels, playlists, history)

5. UI Rendering: Router mounts component tree and renders initial view

For detailed bootstrap implementation, see Application Bootstrap.

Sources: index.html1-40 src/index.tsx

Deployment Architecture

Diagram: Multi-Cloud Deployment Strategy

Production Instances

Environment	URL	Purpose
Production	https://ytify.pp.ua	Main production instance
Development	https://dev--ytify.netlify.app	Testing branch deployment
PR Previews	deploy-preview-*--ytify.netlify.app	Feature preview per PR

The deployment leverages:

• Netlify for static hosting, edge functions, and PR preview system
• Vercel for compute-intensive API functions
• GitHub Actions for continuous integration (implied by deployment badges)

This dual-cloud strategy provides redundancy and optimization: Netlify handles proximity-based operations (stream proxying, sync) while Vercel handles compute-intensive tasks (JioSaavn integration).

Sources: README.md35-36 CONTRIBUTING.md11-21

Data Storage Architecture

Diagram: localStorage Schema and Cloud Sync

localStorage Key Schema

Key	Data Type	Purpose	Managed By
config	Object	User preferences (quality, theme, language, stableVolume)	src/lib/config.ts
drawer	Object	UI state (recentSearches, discoveryCache, subfeed, gallery)	src/lib/config.ts
library_meta	Object	Collection update timestamps: { [collectionName]: { updated: number } }	src/lib/library.ts
library_tracks	Map	Track metadata cache: Map<trackId, TrackMetadata>	src/lib/library.ts
library_favorites	Map	Favorite tracks: Map<trackId, CollectionItem>	src/lib/library.ts
library_channels	Map	Subscribed channels: Map<channelId, CollectionItem>	src/lib/library.ts
library_playlists	Map	Saved playlists: Map<playlistId, CollectionItem>	src/lib/library.ts
library_history	Map	Playback history: Map<trackId, CollectionItem>	src/lib/library.ts
library_listenLater	Map	Listen later queue: Map<trackId, CollectionItem>	src/lib/library.ts
dbsync_dirty_tracks	Set	Modified track IDs for delta sync: Set<trackId>	src/lib/cloudSync.ts
dbsync_hash	string	Unique sync endpoint identifier	src/lib/cloudSync.ts

Cloud Synchronization Protocol

The sync implementation in src/lib/cloudSync.ts uses a delta sync algorithm:

1. Dirty Tracking: addDirtyTrack() adds modified track IDs to dbsync_dirty_tracks
2. Scheduled Sync: runSync() triggers periodic synchronization
3. Delta Sync: Only sends changed tracks via PUT /sync/:hash
4. Conflict Resolution: Uses ETag headers for optimistic locking
5. Full Sync: pullFullLibrary() and pushFullLibrary() for initial sync

The sync endpoint is hash-based (/sync/:hash) for privacy:

• No user identification required
• Hash stored only in browser localStorage
• Server stores data keyed by hash in Netlify Blobs

For detailed sync implementation, see Cloud Synchronization.

Sources: src/lib/config.ts src/lib/library.ts src/lib/cloudSync.ts netlify/edge-functions/sync.ts README.md28

Project Structure

Diagram: Codebase Organization

Directory Layout

Directory	Purpose	Key Files
Root	Configuration and entry	index.html package.json vite.config.ts tsconfig.json
src/	Frontend application	src/index.tsx src/App.tsx
src/components/	UI components	Player.tsx Queue.tsx Library.tsx Hub.tsx Search.tsx
src/stores/	State management	playerStore.ts queueStore.ts store.ts navStore.ts
src/lib/	Business logic	player.ts cloudSync.ts library.ts helpers.ts config.ts
src/locales/	Translations	en.json fr.json ru.json etc. (17+ languages)
src/types/	TypeScript definitions	Type declarations for external modules
netlify/edge-functions/	Edge functions	fallback.ts sync.ts s.ts
api/	Vercel functions	find.ts album.ts
public/	Static assets	Icons, images, PWA manifest

For detailed project structure documentation, see Project Structure.

Sources: index.html package.json vite.config.ts src/ netlify/edge-functions/ api/

Getting Started

To use ytify:

1. Web Access: Visit https://ytify.pp.ua
2. Install as PWA: Use browser's "Install App" option
3. Mobile: Add to home screen for native-like experience

To develop ytify:

1. Clone the repository
2. Install dependencies with npm i
3. Start dev server with npm run dev

For detailed development setup, see Installation and Setup and Development Environment Setup.

Sources: README.md34-78

Key Architectural Decisions

Solid.js Framework

Decision	Rationale	Implementation
Fine-grained reactivity	No virtual DOM diffing overhead	src/stores/playerStore.ts uses createStore()
Smaller bundle size	~7KB vs React's ~40KB	Built with vite.config.ts
Native TypeScript	Type safety without additional setup	tsconfig.json with strict mode
Performant rendering	Direct DOM updates, no reconciliation	SolidJS createSignal() and createMemo()

Multi-Cloud Deployment

Service	Use Case	Key Files
Netlify	Static hosting, PR previews, edge functions	netlify/edge-functions/ index.html
Vercel	Compute-intensive API functions	api/find.ts api/album.ts
Netlify Edge	Low-latency proxying, metadata fetching	fallback.ts sync.ts
Vercel Functions	JioSaavn integration with fast cold starts	api/album.ts processes album metadata

Local-First Data Architecture

Principle	Implementation	Code Reference
No server-side tracking	All analytics disabled	index.html has no tracking scripts
Offline-first	Service worker caches resources	vite.config.ts
Privacy by design	Data stored in browser localStorage	src/lib/config.ts manages local state
Optional cloud sync	Hash-based anonymous endpoints	src/lib/cloudSync.ts
On-device recommendations	No data sent to server	src/lib/library.ts generates recommendations

Invidious Integration

Feature	Reason	Implementation
Privacy-respecting	No Google tracking	src/lib/helpers.ts calls Invidious API
Progressive streaming	Low-bandwidth support	src/lib/player.ts handles adaptive formats
No API key	Community instances freely accessible	src/stores/store.ts manages instance list
Stream proxying	CORS and bandwidth optimization	src/lib/helpers.ts

Serverless Edge Functions

Function	Purpose	Why Edge vs Traditional
fallback.ts	Video metadata fetching	Low latency, proximity to users
sync.ts	Library synchronization	Optimistic locking with ETags
s.ts	Link preview generation	Fast Open Graph rendering

For detailed architectural implementation, see Architecture Overview.

Sources: README.md86-92 vite.config.ts tsconfig.json src/stores/playerStore.ts src/lib/config.ts src/lib/cloudSync.ts src/lib/helpers.ts netlify/edge-functions/ api/

Community and Contributions

ytify is actively developed with community contributions:

• Telegram Group: @ytifytg
• Issue Tracker: GitHub Issues
• Translation: Weblate
• PR Preview System: Every pull request gets a live preview URL

For contribution guidelines, see Contributing Guidelines.

Sources: README.md38 README.md44-45 README.md82-84 CONTRIBUTING.md1-21