Piped Documentation

1. Project Overview & Quickstart (TeamPiped/Piped) Copy Chapter

Piped

An open-source alternative frontend for YouTube which is efficient by design.

A list of public instances can be found at the documentation here.

The Problem

YouTube has an extremely invasive privacy policy which relies on using user data in unethical ways. You give them a lot of data - ranging from ideas, music taste, content, political opinions, and much more than you think.

By using Piped, you can freely watch and listen to content without the fear of prying eyes watching everything you are doing.

Features: Copy Chapter

User Features

• No Ads
• No Tracking
• Lightweight on server and client
• Infinite Scrolling
• Light/Dark themes
• Login
• Feeds
• Playlists
• Integration with SponsorBlock
• Integration with LBRY for streaming
• Integration with Return YouTube Dislike via RYD-Proxy
• 4K support
• No connections to Google's servers
• Playing just audio
• PWA support
• Locally saved Preferences
• Available in many languages, thanks to our translators
• Embedded video support
• No age restriction
• Bypasses Geo restrictions if possible through a federated network

Technical Features

• Multi-region load-balancing
• Performant by design, designed to handle 1000s of users concurrently
• Does not use official YouTube APIs
• Uses NewPipeExtractor to extract information
• Public JSON API
• Federated protocol on Matrix to let instances collaborate with each other

Having trouble? Copy Chapter

If you have any general questions regarding how Piped works or trouble setting up your own instance, please consult the following public chat rooms and documentation for help. Please use these platforms exclusively for such cases and do NOT open an issue.

Public Chat Rooms/Communities Copy Section

• You can join us via Matrix at #piped.
• You can join us on Lemmy on the [email protected] community.

Self-Hosting Copy Section

See https://docs.piped.video/docs/self-hosting/ for more details.

The source code of the documentation website is available at https://github.com/TeamPiped/Documentation.

Documentation Copy Section

The documentation can be found at https://docs.piped.video (accessible via IPNS as well).

The API specification is located at https://github.com/TeamPiped/OpenAPI.

Extensions Copy Chapter

To redirect all YouTube links to Piped, you are highly recommended to use either Piped-Redirects, Libredirect or Predirect.

Contributing Copy Chapter

Translations Copy Section

You can help by translating the project to a language you speak at https://hosted.weblate.org/projects/piped/frontend/

Mirrors Copy Section

• Cloudflare Pages - cf.piped.video
• Vercel - vc.piped.video
• Render - re.piped.video
• Fleek - fl.piped.video
• DigitalOcean - do.piped.video
• Netlify - nf.piped.video
• Azure - az.piped.video

Forking, and contributing Copy Section

• Fork the repository on GitHub: https://github.com/TeamPiped/Piped/fork
• Create your feature branch: git checkout -b my-awesome-feature
• Stage your files git add .
• Commit your changes git commit -am 'Add awesome new feature'
• Push to the branch git push origin my-awesome-feature
• Create a new pull request: https://github.com/TeamPiped/Piped/compare

Development Setup Copy Section

pnpm install

Compiles and hot-reloads for development Copy Section

pnpm dev

You can now make changes and view then in realtime!

Donations Copy Chapter

Donations (to Kavin) can be made at:

• bc1qhq8zjxmu405nvp37njj6zv3s980zg400pu9jfe (BTC)
• 0x1D77D4cfB1a947514241bcf19B1F04738495e2fD (ETH)
• 84wyyeGTrg4U1daJufi78bAFrBQgdRhmxJZvgYv8dAFeFVwkJaBEmw5C7fNniUM9n4jfrz3NeG32Agxtp7JNAcCUFPACfwA (XMR, aka Monero)
• nano_1ngejzydncche4rdua3iebhj7sa95pw5geq4pb8phugtjf3tku933ktjb4pq (Nano)
• XpzgouDTKCUuE8a92XqjX9b43gKL8oLihw (Dash)

FIAT donations can be made at:

• https://liberapay.com/kavin (Initial author)
• https://liberapay.com/Bnyro (Project maintainer)

Contributions in any other form are also welcomed.

Made with Piped

Mobile/desktop apps

• LibreTube - Alternative frontend for YouTube for Android.
• Yattee - Alternative frontend for YouTube for MacOS / iOS.
• YTDLnis - Video and audio downloader for Android that uses Piped to update formats.
• Pipeline - Alternative frontend for YouTube for Linux.
• PlasmaTube - Alternative frontend for YouTube for Linux.
• Harmony Music - YouTube Music alternative for Android/Windows/Debian, built with Flutter that supports piped linking for playlists.

Web apps

• Hyperpipe - Alternative privacy respecting front-end for YouTube Music.
• ytify - Complementary audio streaming frontend for YouTube & YouTube Music.
• Piped-Material - Fork of Piped, focusing on better performance and a more usable design.
• Musicale - Alternative frontend for YouTube Music with style.

Not Under Active Development

• PsTube - Watch and download videos without ads on Android, Linux, Windows, iOS, and Mac OSX.
• VibeYou - Privacy focused music player for Android supporting playback via Piped.
• conduit - Alternative frontend for YouTube, with a modern player and watch together capabilities.
• DeskVideo - Desktop styled, customizable alternative frontend for YouTube.
• ReacTube - Privacy friendly & distraction free YouTube frontend.
• vidyodl - Simple API to download videos from YouTube, using Piped.
• Piped Addon for Kodi - Kodi plugin for Piped.

YourKit Copy Chapter

YourKit has given an open source license for their profiler, greatly simplifying the profiling of Piped's performance.

YourKit supports open source projects with its full-featured Java Profiler.
YourKit, LLC is the creator of YourKit Java Profiler
and YourKit .NET Profiler,
innovative and intelligent tools for profiling Java and .NET applications.

2. Official Technical Reference & Guides (TeamPiped/documentation) Copy Chapter

File: README.md Copy Chapter

Documentation

Documentation on the core architecture of Piped and it's backend.

Instances Copy Chapter

New instances will be added at the bottom of the page. Improperly configured instances may be removed without any warnings. Instances with a CDN will be prioritized compared to instances without one.

To add a new instance, add a new row in content/docs/public-instances/index.md and create a pull request at the .

File: content/docs/api-documentation/index.md Copy Chapter

title: "API Documentation" weight: 4 summary: A guide on how to use Piped's API. Copy Chapter

API Servers Copy Chapter

A list of public instances can be found here.

To keep up-to date with the instances list, you are expected to dynamically parse it.

An example on how this can be done is available at https://github.com/TeamPiped/Piped/blob/85e2296dc410fd20375d623465900c55b5483da9/src/components/Preferences.vue#L202-L221

Base URL Copy Chapter

For all endpoints in this documentation, you will have to use an API url as a prefix. For example, the official instance's base URL would be https://pipedapi.kavin.rocks.

API Paths Copy Chapter

The OpenAPI specification for Piped is located at https://github.com/TeamPiped/OpenAPI/main/swagger.yaml. In order to properly view and inspect the available API routes, you
can open https://petstore.swagger.io in a web browser, paste https://raw.githubusercontent.com/TeamPiped/OpenAPI/main/swagger.yaml into the text field at the top and finally
click explore. Swagger UI allows you to test the documented API paths and see the required and returned parameters for requests and their responses.

File: content/docs/architecture/index.md Copy Chapter

title: "Architecture" weight: 4 summary: How is Piped architectured? Copy Chapter

How is Piped's architecture? Copy Chapter

Piped has 3 components:

• A frontend in VueJS
• A backend in Java which uses NewPipeExtractor
• A proxy in Rust

Frontend Copy Chapter

• Uses shaka-player for streaming.
• Uses a router for a single page application.

Backend Copy Chapter

• Uses Java 17
• Uses a JNI wrapper around Reqwest, a Rust HTTP client.
• Uses ActiveJ to achieve maximum performance. Which is really fast
• Supports OpenJ9, and Hotspot
• Each running instance should configure their own proxy, thus allowing multi-gigabit content delivery.
• Uses ~70-130 MB of ram. (on OpenJ9)

Database Copy Chapter

• We currently support PostgreSQL, CockroachDB and YugabyteDB for high availability deployments.

Proxy

• Uses Rust.
• Has HTTP/2 support.
• Uses actix-web and reqwest for maximum performance.
• Low memory footprint and high throughput.
• Converts jpeg images to webp on the fly to reduce bandwidth usage.

Server-Side Caching

Caching is done at a Reverse-Proxy/CDN level to reduce the load to the backend. This also makes it more scalable.

LBRY

LBRY streams are automatically used to stream content via LBRY if the same video is available there.

File: content/docs/config/index.md Copy Chapter

title: "Configuration" weight: 4 summary: A list of all configuration options and what they do. Copy Chapter

Configuration Copy Chapter

PORT: Copy Section

The port the backend should listen on.

PROXY_PART: Copy Section

The Base URL address of the proxy. You should use https://github.com/TeamPiped/piped-proxy for this. Each instance of the backend should have this on a different hostname for maximum bandwidth.

CAPTCHA_BASE_URL: Copy Section

The base of the URL of the captcha solving service. In most cases, you would use https://api.capmonster.cloud/ or https://anti-captcha.com/

CAPTCHA_API_KEY: Copy Section

The api key to use when connecting to the captcha solving service.

File: content/docs/parameters/index.md Copy Chapter

title: "URL Parameters" weight: 4 summary: A list of all parameters that can be used in the default frontend. Copy Chapter

URL Parameters Copy Chapter

instance Copy Section

Example: instance=https://pipedapi.kavin.rocks

This parameter can be used to force the frontend to use a specific instance.

watchHistory Copy Section

Example: watchHistory=true

This parameter can be used to enable saving of watch history in the IndexedDB.

hl Copy Section

Example: hl=fr

This parameter can be used to set the language to be used by the frontend.

region Copy Section

Example: region=us

This parameter can be used to set the region to be used when fetching the trending videos.

theme Copy Section

Example: theme=light

This parameter can be used to set the theme to be used by the frontend.

playerAutoPlay Copy Section

Example: playerAutoPlay=true

This parameter can be used to control the autoplay of the player on a page's load.

listen Copy Section

Example: listen=true

This parameter can be used to enable audio-only mode on a particular video.

quality Copy Section

Example: quality=1080

This parameter can be used to set the quality of the video on a page.

bufferGoal Copy Section

Example: bufferGoal=120

This parameter sets the buffer goal of the video in seconds.

minimizeDescription Copy Section

Example: minimizeDescription=true

This parameter can be used to hide the description of a video by default.

minimizeComments Copy Section

Example: minimizeComments=true

This parameter can be used to hide the list of comments on the bottom, by default.

minimizeRecommendations Copy Section

Example: minimizeRecommendations=true

This parameter can be used to hide the list of recommendations on the right, by default.

enabledCodecs Copy Section

Example: av1,vp9,avc

This parameter can be used to set the enabled codecs for the the video player.

disableLBRY Copy Section

Example: disableLBRY=true

This parameter can be used to disable using LBRY's servers for streaming.

proxyLBRY Copy Section

Example: proxyLBRY=false

This parameter can be used to use LBRY's servers instead of Google's servers for streaming when available.

sponsorblock Copy Section

Example: sponsorblock=true

This parameter can be used to enable or disable SponsorBlock on a video.

selectedSkip Copy Section

Example: selectedSkip=sponsor,intro,outro,preview,interaction,selfpromo,music_offtopic,poi_highlight,filler

This parameter can be used to set the parameters to be used in SponsorBlock.

volume Copy Section

Example: volume=0.75

This parameter can be used to set the volume of the video player.

rate Copy Section

Example: rate=2

This parameter can be used to set the playback rate of the video player.

autoplay Copy Section

Example: autoplay=true

This parameter can be used to set the autoplay of the next video.

File: content/docs/public-instances/index.md Copy Chapter

title: "Public instances" weight: 4 summary: List of publicly available instances Copy Chapter

It's highly NOT recommended to be using frontends of the hosted instances directly from this page, as they're not check if they're configured properly, or modified without disclosing their source code as per the AGPL. You're always recommended to use piped.video, IPFS, or the mirrors mentioned in the README.

You can switch instances by using the instance switcher in the preferences page. Likewise, you can also set the instance query parameter with an API URL to force the frontend to use an instance.

File: content/docs/self-hosting/index.md Copy Chapter

title: "Self-Hosting" weight: 4 summary: How can I Self-Host Piped? Copy Chapter

Self-Hosting

There are two simple ways to self-host Piped.

• Bring your own reverse proxy (recommended) - This is the recommended way to self-host Piped. You can use any reverse proxy you want, and must configure TLS certificates yourself.
• Using Caddy - This would use Caddy on port 80 and 443, and automatically configure TLS certificates for you. However, it would be difficult to host multiple services on the same server.

Because YouTube tends to ban IP addresses, it is recommended to either

• use the IPv6 rotator made by the Invidious team - This is the recommended way because it's easier to set up and doesn't increase loading times.
• use a VPN or proxy between the Piped backend/proxy and YouTube.
  to keep the instance running if you plan to make your instance public or to have a lot of users.

Docker Compose Caddy AIO script Copy Chapter

First, install git, docker, and the compose plugin for docker.

Run git clone https://github.com/TeamPiped/Piped-Docker.

Then, run cd Piped-Docker.

Then, run ./configure-instance.sh and fill in the hostnames when asked. Choose caddy as the reverse proxy when asked.

Now, create A (and AAAA) records to your server's public IP with the hostnames you had filled in above.

Finally, run docker compose up -d and you're done!

Consider joining the federation protocol at https://github.com/TeamPiped/piped-federation#how-to-join

Docker Compose Nginx AIO script Copy Chapter

Note: This setup requires you to have your own reverse proxy in addition to the one provide, and requires you to configure TLS manually.

First, install git, docker, and the compose plugin for docker.

Run git clone https://github.com/TeamPiped/Piped-Docker.

Then, run cd Piped-Docker.

Then, run ./configure-instance.sh and fill in the hostnames when asked. Choose nginx as the reverse proxy when asked.

Now, create A (and AAAA) records to your server's public IP with the hostnames you had filled in above.

Run docker compose up -d.

Forward traffic to 127.0.0.1:8080 with your reverse proxy, along with the Host header.

For example, in nginx, you would do the following:

server {
    listen 80;
    server_name hostname; # For all 3 hostnames

    location / {
       proxy_pass http://127.0.0.1:8080;
       proxy_set_header Host $host;
    }
}

Here's an example with Apache:

<VirtualHost *:443>
    ServerName hostname # For all 3 hostnames

    ProxyPass /  http://127.0.0.1:8080/  nocanon
    ProxyPassReverse /  http://127.0.0.1:8080/

    ProxyPreserveHost On

    AllowEncodedSlashes On

    # TLS configuration here
</VirtualHost>

Here's an example with Traefik using Docker compose labels:

This must be applied on the nginx container.

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.piped.rule=Host(`piped.yourdomain.tld`) || Host(`pipedapi.yourdomain.tld`) || Host(`pipedproxy.yourdomain.tld`)"
  - "traefik.http.routers.piped.entrypoints=web"

Here's an example using Caddy:

hostname, hostname2, hostname3 {
    reverse_proxy http://127.0.0.1:8080
}

Finally, configure your TLS certificates if necessary. For nginx, you could use certbot with the nginx plugin.

Consider joining the federation protocol at https://github.com/TeamPiped/piped-federation#how-to-join

Manually updating

Run docker run --rm -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower --run-once piped-frontend piped-backend piped-proxy varnish nginx caddy postgres watchtower

Docker Compose with system Nginx Copy Chapter

WARNING: This setup is not recommended, as it is difficult to setup and maintain.

First download the files required to run Piped.

mkdir piped && cd piped
wget https://raw.githubusercontent.com/TeamPiped/Piped-Backend/master/config.properties
wget https://raw.githubusercontent.com/TeamPiped/Piped-Backend/master/docker-compose.yml

Create two A records - one for the proxy and one for the api.
Note: Each running instance of the proxy should have it's own record to maximize performance.

For example:
A pipedapi.kavin.rocks
A pipedproxy-bom.kavin.rocks

Now, edit your config.properties file to reflect the changes.

Now, run piped with the following command:

docker compose up -d

Now, find your nginx user's and group's id.

You can do this by running the following command:

cat /etc/passwd

Then look for a line which starts with www-data or nginx, here is an example of that:

www-data:x:33:33:www-data:/var/www:/usr/sbin/nologin

Now, you have the user and group id - 33:33.

Now, run the proxy with the following command, while replacing the user parameter with what you just found:

docker run -d --network=host -v "/var/run/ytproxy/:/app/socket" --user 33:33 --restart unless-stopped 1337kavin/piped-proxy:latest

You can now use watchtower to enable automatic container updates (optional):

docker run -d \
    --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    containrrr/watchtower

Now, create an nginx snippet like so:

/etc/nginx/snippets/ytproxy.conf

proxy_buffering on;
proxy_buffers 1024 16k;
proxy_set_header X-Forwarded-For "";
proxy_set_header CF-Connecting-IP "";
proxy_hide_header "alt-svc";
sendfile on;
sendfile_max_chunk 512k;
tcp_nopush on;
aio threads=default;
aio_write on;
directio 16m;
proxy_hide_header Cache-Control;
proxy_hide_header etag;
proxy_http_version 1.1;
proxy_set_header Connection keep-alive;
proxy_max_temp_file_size 32m;
access_log off;
proxy_pass http://unix:/var/run/ytproxy/actix.sock;

Now, create a site configuration file:

/etc/nginx/sites-available/piped.conf

server {
    listen 80;
    listen 443 ssl http2;
    ssl_certificate /etc/ssl/certs/kavin.rocks.pem;
    ssl_certificate_key /etc/ssl/private/kavin.rocks.key;
    ssl_early_data on;
    server_name pipedapi.kavin.rocks; # Change this depending on what domain you are using

    location / {
       proxy_pass http://127.0.0.1:8080;
    }
}

server {
    listen 80;
    listen 443 ssl http2;
    ssl_certificate /etc/ssl/certs/kavin.rocks.pem;
    ssl_certificate_key /etc/ssl/private/kavin.rocks.key;
    ssl_early_data on;
    server_name pipedproxy-bom.kavin.rocks; # Change this depending on what domain you are using

    location ~ (/videoplayback|/api/v4/|/api/manifest/) {
       include snippets/ytproxy.conf;
       add_header Cache-Control private always;
       proxy_hide_header Access-Control-Allow-Origin;
    }

    location / {
       include snippets/ytproxy.conf;
       add_header Cache-Control "public, max-age=604800";
       proxy_hide_header Access-Control-Allow-Origin;
    }
}

Finally, reload the nginx service and you are done!

IPv6 rotator using Docker

This requires you to already have set up a working Piped instance using Docker Compose as described above.

First of all, make sure that your server supports IPv6 by running curl -m 5 ipv6.icanhazip.com and confirm that an IPv6 address is returned as response. If it doesn't, this tutorial won't work.

Next, you need to enable IPv6 in Docker. First, edit /etc/docker/daemon.json and insert

{
  "experimental": true,
  "ip6tables": true
}

After, edit the docker-compose.yml of Piped and insert the following at the end of the file

networks:
  default:
    enable_ipv6: true
    ipam:
      config:
        - subnet: 2001:db8::/112

Now restart Docker. To confirm everything worked as expected and your instance now uses IPv6, run docker exec -it piped-backend curl icanhazip.com. If you see an IPv6 address here, you successfully force-enabled IPv6.

More information about Docker and IPv6 can be found at https://docs.docker.com/config/daemon/ipv6/.

Last but not least, the Smart IPv6 Rotator (credits to the Invidious team!) has to be set up. In order to do so, please follow the steps at its GitHub repository after installing the required Python packages. That's it, your Piped instance now periodically rotates its IPv6 address!

File: content/docs/why/index.md Copy Chapter

title: "Why" weight: 4 summary: Why did I create Piped? Copy Chapter

Why did I create Piped? Copy Chapter

YouTube has an extremely invasive privacy policy which relies on using user data in unethical ways.

Here are some things about YouTube:

• Tracking via third-party cookies for other purposes without your consent.
• YouTube can delete your content if you violate the terms
• Reduction of legal period for cause of action
• YouTube may use your personal information for marketing purposes
• YouTube can view your browser history
• YouTube can use your content for all their existing and future services
• YouTube gathers information about you through third parties
• YouTube can license user content to third parties
• YouTube provider makes no warranty regarding uninterrupted, timely, secure or error-free service
• Deleted videos are not really deleted
• Your data may be processed and stored anywhere in the world
• YouTube is only available to users over a certain age
• YouTube can suspend your account for several reasons
• YouTube has non-exclusive use of your content
• The court of law governing the terms is in the US
• YouTube collects your IP address for location use

Source: https://tosdr.org/en/service/274

A lot of inspiration came from NewPipe and Invidious.

I created Piped to fix issues in NewPipe and Invidious which are architectural issues and cannot be fixed easily.

NewPipe Copy Section

• Your IP is exposed to YouTube.
• Feeds are slow to load/update in comparison to YouTube.

Invidious Copy Section

• Uses way too much resources.
• Total bandwidth limited by the peak capacity of the load balancer.
• Coded in Crystal, a language that is relatively hard for beginners.
• Caching is done at a backend level.
• Invidious was a learning project.
• Invidious crashes all the time.
• Various hacks are required to keep an instance running at a reasonable stability.

However, there are some drawbacks of Piped:

• JavaScript is required
• Browsers without Service-Workers support will feel significantly slower. Eg: Tor Browser

File: content/docs/_index.md Copy Chapter

title: "Overview" weight: 1 Copy Chapter

Piped Copy Chapter

Welcome to the Documentation of Piped.

File: content/docs/faq.md Copy Chapter

title: "FAQ" weight: 4 summary: Frequently Asked Questions, and their answers. Copy Chapter

FAQ

Videos take a long time to buffer Copy Chapter

This is a known issue, and is due to YouTube throttling the download speed of videos. We are working to find a workaround for this, collaboarively with other projects. You could try using a different instance to work around the issue.

"It's not working most of the time" Copy Chapter

Try another instance, instances in the instance switcher are checked to be working every minute. You likely want to choose an instance with a high uptime too.