---
title: send2kodi
related:
  - "[Kodi](../guides/kodi.md)"
  - "[wl2kodi](wl2kodi.md)"
  - "[browser2kodi](browser2kodi.md)"
  - "[pm-user-repository](pm-user-repository.md)"
categories:
  - Tools and applications
---

**send2kodi** sends YouTube links, links to media files and streams, and the
videos, music and pictures on your computer to Kodi, from the command line.
It is a single Python script with no dependencies.

```
$ send2kodi https://youtu.be/jNQXAC9IVRw
$ send2kodi ~/Videos/holidays.mkv
$ send2kodi ~/Videos/Some.Show/
$ send2kodi ~/Pictures/beach/
```

## How it works

Everything goes through Kodi's JSON-RPC API, so nothing has to be installed
on the Kodi box beyond two common add-ons.

| You send | Kodi plays it with |
|---|---|
| A YouTube video | the YouTube add-on, at the time in the link if it has one (`?t=1m30s`) |
| A link to a media file or stream (`.mp4`, `.mp3`, `.m3u8`…) | Kodi itself, without any add-on |
| Any other URL (Vimeo, Twitch, a YouTube playlist…) | the SendToKodi add-on, which resolves it with yt-dlp on the Kodi side |
| A file on your computer | a small HTTP server on your computer, which Kodi streams from |
| A folder | its videos and songs, subfolders included, in natural order (episode 2 before episode 10); or its pictures, if it has neither |
| Songs | Kodi's music player |
| Pictures | Kodi's picture viewer; several make a slideshow |

The file server serves only the files you named, and the subtitles next to
videos, under a random path that changes every run. It answers only the Kodi
box, and shuts itself down once Kodi has played the files. Seeking works.

## Requirements

- **Your computer:** Linux, Python 3.9 or newer.
- **Kodi:** 18 or newer (`--sub` needs 19), with *Settings → Services →
  Control → Allow remote control via HTTP* enabled.
- The [SendToKodi](https://github.com/firsttris/plugin.video.sendtokodi)
  add-on for web pages, and the YouTube add-on for YouTube.

## Installation

```
$ git clone https://github.com/hugoocoto/send2kodi
$ cd send2kodi
$ ./install.sh
```

The installer asks for the Kodi box's address, checks that Kodi answers there
and which add-ons it has, and installs `~/.local/bin/send2kodi` and its
settings file. `./install.sh --uninstall` takes it back out.

It is also available through the [pm user repository](pm-user-repository.md).

## Usage

```
$ send2kodi URL_OR_FILE ...           # play now, replacing whatever is playing
$ send2kodi -q URL_OR_FILE ...        # add to the end of Kodi's queue
$ send2kodi -q -C                     # queue the URLs or paths in the clipboard
$ ls ~/Videos/*.mkv | send2kodi -     # read them from stdin
$ send2kodi -s 1:02:30 film.mkv       # start at 1h02m30s
$ send2kodi --sub film.es.srt URL     # with these subtitles
$ send2kodi --bg ~/Videos/film.mkv    # serve the file in the background
$ send2kodi --pause
$ send2kodi --stop
```

When playing now, it waits until Kodi really starts playing, and otherwise
says why not: a link that did not resolve, or a firewall between Kodi and
your computer. Kodi accepts any link at once, even one that will never play.

A folder sends its videos and songs, leaving out posters and cover art; a
folder with only pictures makes a slideshow.

### Subtitles

Subtitle files named after a local video, next to it or in a `Subs` folder
(`film.srt`, `film.en.srt`, `Subs/film.es.forced.srt`…), go along with it.
Kodi finds them the same way it does next to its own files, and lists them in
its subtitle menu. Any other subtitle file can be given with `--sub`.

## Configuration

`~/.config/send2kodi/config` holds `KEY=value` lines. Every setting also works
as an environment variable, and command-line flags beat both.

| Setting | Default | Meaning |
|---|---|---|
| `KODI_HOST` | | Address or hostname of the Kodi box (`-H`) |
| `KODI_PORT` | `8080` | Kodi's web server port (`-p`) |
| `KODI_USER`, `KODI_PASS` | `kodi`, empty | Web server login, if Kodi has one |
| `YOUTUBE` | `addon` | `ytdlp` sends YouTube through SendToKodi too (`--ytdlp`) |
| `BACKGROUND` | `no` | `yes` makes `--bg` the default |
| `START_TIMEOUT` | `60` | Seconds to wait for playback |
| `SERVE_PORT` | `8765` | Port local files are served on |
| `SERVE_IP` | autodetected | Address Kodi reaches this computer on |

> [!TIP]
> If URLs work but local files don't, Kodi cannot reach your computer: check
> that a firewall lets `SERVE_PORT` through.

## See also

- [Kodi](../guides/kodi.md), setting Kodi up for this and its sibling tools
- [Source code](https://github.com/hugoocoto/send2kodi) (MIT)
- [wl2kodi](wl2kodi.md), to mirror the whole screen instead
- [browser2kodi](browser2kodi.md), to send from the browser's right-click menu