Documentation
How Kinode Media Server works, how to run it as your self-hosted home media server, and what to do when it misbehaves.
What this is
Kinode Media Server serves the video and music already on your own disks to the devices you already own. It runs on one machine in your house. Everything else, meaning phones, tablets, TVs and browsers, connects to that machine.
There is no subscription, and no feature is held back for a paid tier. Remote streaming, hardware transcoding, subtitle handling and library sharing are all included because there is nothing to sell you.
The pieces
| Piece | Runs where | What it does |
|---|---|---|
| The server | Your machine | Reads your library, serves the web app, streams and converts video and audio. |
| The hub | kinode.tv | An account system and a directory. It helps apps find your server when you are away from home. It never touches your video. |
| Apps | Phones, TVs | Android and Roku clients. They talk to your server directly whenever they can. |
| The Discord bot | Your machine, optional | Announcements, library search, and music in voice channels. |
The hub stores your account, a list of your servers, and their addresses. It does not store what you watch, who your managed users are, or anything about your files. When an app streams video, it connects to your server directly and the hub is not in the path. If the hub is offline, playback keeps working.
Two ways it can be set up
The installer produces a bundled install. A complete ffmpeg with every codec compiled in ships inside it, so nothing else has to be present for playback to work.
There is also an attached mode, where the server reads an existing media library database and uses external binaries. That is configured through data/engine.json or the ENGINE_* environment variables. Bundled binaries win when both are present, because the bundled ffmpeg carries codecs that vendor builds leave out.
A bundled install has its own scanner. It walks your folders, reads each file with the bundled ffprobe, and writes the library itself, so nothing else has to be installed to build a library.
Installing on Windows
What is inside the installer
Everything the server needs is in the file you download. Nothing is fetched during setup, so a slow or missing internet connection does not break the install.
| Bundled | Why |
|---|---|
| Node runtime | The server is written in JavaScript. The runtime ships alongside it so you never install one yourself, and a system Node upgrade cannot break the server. |
| ffmpeg, full build | Every common codec is compiled in. This is what lets odd files play instead of failing. Vendor ffmpeg builds often ship without the video codecs for licensing reasons, which is exactly the problem this avoids. |
| Service wrapper | Turns the server into a Windows service so it starts with the machine and restarts if it stops. |
| The Discord bot | Optional. You choose during setup whether to include it. |
The unknown publisher warning
Windows will show a blue SmartScreen box saying it protected your PC and naming an unknown publisher. Choose More info, then Run anyway.
That warning is about a code signing certificate, which costs a few hundred dollars a year from a certificate authority. Until one is bought, every download shows this. It is not a statement about what the installer does. If that bothers you, the source is public and you can build it yourself.
Ports
| Port | Protocol | Used for |
|---|---|---|
5466 | TCP | The web app and the API. This is the one you open in a browser. |
5467 | UDP | Local discovery, so apps on your network find the server without anyone typing an address. |
5468 | TCP | The Discord bot's local API. Only installed if you chose the bot. |
5466 spells KINO on a phone keypad. The block was chosen to stay clear of Plex, which uses 32400 for its web interface and 32410 through 32414 for discovery. An earlier build of this server used 32402 and 32410, and 32410 collided with Plex discovery on any machine running both. That is fixed, and it is the reason the ports look arbitrary.
You can change the main port during setup. The installer validates it is between 1024 and 65535, writes it into the service definition, and uses it for the shortcuts and the firewall rule.
The firewall rule
If you leave the firewall task ticked, setup runs two netsh commands and creates two inbound rules:
netsh advfirewall firewall add rule name="Kinode Media Server"
dir=in action=allow protocol=TCP localport=5466 profile=private,domain
netsh advfirewall firewall add rule name="Kinode Media Server discovery"
dir=in action=allow protocol=UDP localport=5467 profile=private,domain
Both are scoped to the private and domain profiles. They do not apply to public networks, which is what Windows calls a coffee shop or an untrusted connection.
A firewall rule lets devices on your own network reach the server. Reaching it from outside your house additionally needs a port forward on your router, which is a separate thing you have to do deliberately. See Remote access.
Where your data lives
The program goes in C:\Program Files\Kinode Media Server. Your data goes somewhere else entirely:
C:\ProgramData\Kinode Media Server\
data\
accounts.db accounts, profiles, PINs, watch history, playlists
secret.key signs sign-in tokens
plugins\ installed plugins
trickplay\ seek preview images
subtitles\ downloaded subtitle files
logs\ service logs, rolled at 10 MB, four kept
This split is deliberate. A service account cannot write into Program Files, and keeping data outside the program directory means an upgrade or a reinstall never touches your accounts or your watch history.
The server finds this directory through the KINODE_DATA environment variable, which the installer sets in the service definition. Running from a source checkout with no such variable, the data sits beside the code in data\, which is what you want while developing.
Service or window
Ticking the service task during setup installs a Windows service called Kinode Media Server. It starts automatically after boot, restarts itself ten seconds after a crash, and writes rolling logs.
sc query KinodeMediaServer
net stop KinodeMediaServer
net start KinodeMediaServer
If you skip the service, use the Start Kinode Media Server.cmd shortcut that setup writes into the install folder. It opens a console window and the server runs until you close it. That is useful for testing because you see errors immediately.
Registry entries
Setup writes five values under HKLM\Software\Kinode\MediaServer: InstallPath, DataPath, Version, Port, and Architecture. Uninstalling removes the key. Nothing else in the registry is touched, and no file associations or shell extensions are registered.
Uninstalling
Uninstall from Settings, Apps, or from the Start menu shortcut. It stops the service, removes it, deletes both firewall rules, and removes the program files.
It then asks whether to remove your accounts, watch history and settings. Choosing No keeps C:\ProgramData\Kinode Media Server intact, which is what you want if you are reinstalling or moving to a new version. Your media files are never touched either way, because the server only ever reads them.
Architectures
There are two builds: x64 for Intel and AMD machines, and arm64 for Windows on ARM laptops. The download page detects which one you need and preselects it, and you can override that.
There is no 32 bit build. Windows 11 has no 32 bit edition, a 32 bit process cannot address more than 4 GB of memory, and video transcoding wants more than that. If you have a real need for one, say so on the forum.
Installing on Linux
Kinode runs on 64-bit Linux as well as Windows. It is the same home media server, built from the same code: the Linux packages carry their own Node runtime and the same full ffmpeg build as the Windows installer, so nothing else has to be installed for playback to work. Get them from the download page.
What it needs
| Need | Detail |
|---|---|
| A 64-bit system | x64 (Intel or AMD), or arm64. The ARM builds have not yet been run on real ARM hardware. |
| systemd | The packages install a systemd service. Docker is the way round this on a system without it. |
| glibc 2.28 or newer | Debian 10, Ubuntu 20.04 and anything later. Tested on Ubuntu 24.04. |
| Readable media folders | The server runs as its own kinode user, which needs read access to your library folders, and write access if you want artwork saved beside your files. |
Installing the .deb (Ubuntu, Debian, Mint)
sudo apt install ./kinode-media-server_1.5.0_amd64.deb
Use the arm64 file on a 64-bit ARM machine. apt installs what the package depends on, creates the kinode user, adds it to the video and render groups so it can use the graphics card, writes /etc/kinode-media-server/kinode.env, and starts the service. Open http://localhost:5466, or the machine's address on port 5466 from another device, to create the first account.
Installing the tarball (any systemd distribution)
tar xzf kinode-media-server-1.5.0-linux-x64.tar.gz
cd kinode-media-server-1.5.0-linux-x64
sudo ./install.sh
install.sh does the same as the .deb, but puts the program in /opt/kinode-media-server and links kinodectl into /usr/local/bin. It takes these options:
| Option | What it does |
|---|---|
--port 5466 | The web port. |
--prefix /opt/kinode-media-server | Where the program goes. |
--data /var/lib/kinode-media-server | Where the library and accounts go. |
--open-firewall | Opens the web port over TCP and 5467 over UDP in ufw or firewalld, if one of them is active. |
--no-start | Installs without starting the service. |
Running a newer install.sh over an existing install upgrades it. Your data and the settings file are kept, and the previous version is kept in /opt/kinode-media-server/.previous.
Docker
No image is published, so there is nothing to pull. The download page has a Dockerfile, a docker-compose.yml and a docker-entrypoint.sh that build an image on your machine from the Linux tarball. They have not been run end to end yet, so treat them as a starting point rather than a tested install.
# one folder holding the three Docker files and the tarball for your machine
nano docker-compose.yml # point /path/to/your/media at your media
docker compose up -d # builds the image, then starts it on port 5466
Your accounts and library are kept in ./data beside the compose file, and your media is mounted read-only at /media. For an NVIDIA card the compose file asks for the GPU, which needs the NVIDIA Container Toolkit on the host; without one, delete its deploy: block. For Intel or AMD, uncomment the devices: lines that pass in /dev/dri.
The service
The server runs as a systemd service called kinode-media-server, as the kinode user. It starts after boot, and systemd starts it again five seconds after it stops for any reason. That is also how Restart in Settings works on Linux: the server exits cleanly and systemd brings it back.
sudo systemctl status kinode-media-server
sudo systemctl restart kinode-media-server
journalctl -u kinode-media-server -f
kinodectl
There is no tray icon on Linux. kinodectl does what the tray did:
| Command | What it does |
|---|---|
kinodectl status | Whether the service is running. |
kinodectl restart | Restarts it. start, stop, enable and disable work too. |
kinodectl logs -f | Follows the log. Without -f it shows the last 200 lines. |
kinodectl open | Opens the web app in a browser, or prints its address when there is no desktop. kinodectl url only prints it. |
kinodectl version | The installed version. |
Where things live
| What | Where |
|---|---|
| Program | /opt/kinode-media-server |
| Accounts, library database, artwork, plugins | /var/lib/kinode-media-server |
| Start-up settings | /etc/kinode-media-server/kinode.env |
| Logs | journalctl -u kinode-media-server, and /var/lib/kinode-media-server/logs |
kinode.env holds the few settings read before the server starts: PORT, KINODE_DATA (the data folder) and KINODE_LOG_FILES, plus commented examples. Everything else is in the web app under Settings. After changing the file, run sudo systemctl restart kinode-media-server. Upgrades keep your copy.
Ports and the firewall
The ports are the same as on Windows: 5466 over TCP for the web app, and 5467 over UDP for discovery on your network. Neither package changes the firewall unless you ask. With the tarball, sudo ./install.sh --open-firewall opens both in ufw or firewalld. Otherwise open them yourself, for example:
sudo ufw allow 5466/tcp
sudo ufw allow 5467/udp
As on Windows, this only lets devices on your own network in. Reaching the server from outside also needs a port forward on your router; see Remote access.
Graphics cards
Hardware converting works on Linux, and is checked when the server starts. Settings, Transcoder shows which encoder passed its test, and the health panel says why any other did not.
- NVIDIA: install the NVIDIA driver so that
nvidia-smiworks. NVENC encoding and NVDEC decoding are then picked up by themselves. This is the tested setup. - Intel and AMD: VA-API, and Quick Sync on Intel, use
/dev/dri. The installer adds thekinodeuser to thevideoandrendergroups for this. On a machine with two cards, choose one withKINODE_VAAPI_DEVICE=/dev/dri/renderD128inkinode.env.
To convert on the processor only, put KINODE_HW_TRANSCODE=0 in kinode.env and restart the service.
Updating
| Installed from | How it updates |
|---|---|
| Tarball | From Settings, Updates, the same way as Windows. The new version is downloaded, checked, and swapped in, and the service restarts. The version it replaced is kept, and sudo /opt/kinode-media-server/uninstall.sh --rollback puts it back. |
| .deb | Install the newer .deb the same way: sudo apt install ./kinode-media-server_<version>_amd64.deb. The service restarts by itself. Settings, Updates says so instead of offering an Update now button. |
| Docker | Put the new release's tarball and Dockerfile in the folder, then run docker compose build and docker compose up -d. |
Uninstalling
# .deb: keeps your library and settings
sudo apt remove kinode-media-server
# .deb: also removes the settings file and the kinode user
sudo apt purge kinode-media-server
# tarball: keeps your library; --purge removes it too
sudo /opt/kinode-media-server/uninstall.sh
After a .deb purge your library is still in /var/lib/kinode-media-server. Delete that folder if you want it gone. Your media files are never touched, because the server only ever reads them.
How Linux differs from Windows
- There is no tray app. Use
kinodectland the web app. - Restart in Settings is a clean exit, and systemd, or Docker, starts the server again.
- The .deb and Docker installs are updated from outside the app. The tarball updates itself like Windows does.
- The firewall is only opened when you ask.
- The Windows-only choices for hardware decoding and encoding, Media Foundation, Direct3D 11 and DXVA2, are not offered. VA-API takes their place.
- File and folder names are case-sensitive, so
Filmsandfilmsare two different folders.
First run
Creating the first account
Open http://localhost:5466. The first account you create becomes the owner of that server, with administrator rights on it. Nothing is emailed and no account is created anywhere else. This account exists only on your machine.
People who run their own server are called owners. The word admin is reserved for staff on this website, meaning the people who moderate the forum and review plugins. The two are unrelated, and owning a server gives you no rights here.
Adding libraries
Go to Settings, then Libraries, and choose Add library. Point it at the directory that holds your media. Give it the right type, because it changes how things are grouped and displayed:
- Movies expects one film per folder or per file.
- TV Shows expects show, then season, then episode.
- Music expects artist, then album, then track.
Naming that scans cleanly
Scanners match on filenames. These layouts work:
Movies\
Blade Runner (1982)\Blade Runner (1982).mkv
Heat (1995)\Heat (1995) Bluray-1080p.mkv
TV Shows\
The Wire\Season 01\The Wire - S01E01 - The Target.mkv
Music\
Radiohead\OK Computer\01 Airbag.flac
A year in parentheses removes almost all ambiguity for films, especially remakes. S01E01 is the most reliably parsed episode format.
The scan
A scan walks the folder, works out what each file is, and writes it into the library database. Artwork and descriptions are fetched afterwards, so titles usually appear before their posters do.
Large libraries take a while. Ten thousand files is normal at tens of minutes, and it is disk bound rather than processor bound.
Libraries also rescan themselves once a day at 3 AM, so files you drop in overnight show up without anyone pressing anything.
Open the library's Edit window and look at Folders. Each folder says whether it exists and what is in it, so an empty folder or a wrong path shows up there. The troubleshooting entry covers the other causes.
Artwork and descriptions
Posters, backgrounds and summaries are fetched after the files are indexed. If a film has the wrong poster it is almost always because the filename matched the wrong title. Renaming the file to include the year and rescanning fixes it.
Profiles and family
Managed users
A managed user is a person on your server who has a display name and nothing else. They have no password and no email address. After you sign in, a screen asks who is watching, and everyone picks their name.
What each managed user gets:
- Their own watch history and Continue Watching row.
- Their own ratings, watchlist, playlists and recommendations.
- Access to exactly the libraries you granted them.
- An optional PIN, between four and eight digits, stored hashed.
Create them from the who-is-watching screen using Manage users. The account owner is always the first tile and cannot be deleted.
They are stored only in your server's database. The hub has no concept of them, no table for them, and no way to learn they exist. Nothing about a managed user ever leaves your machine.
PINs
A PIN gates entering a profile. It is not a password and it does not protect the account, because anyone who is already signed in is inside your server. It stops a child from picking your profile and it stops someone seeing your Continue Watching row.
PINs are stored as bcrypt hashes. There is no way to read one back, including for you. Clear it and set a new one from the same edit screen.
Per-profile library access
Editing a managed user offers either everything on the server, or a specific list of libraries. Access is enforced on the server for every request, so a hidden library cannot be reached by guessing a URL.
A profile can only ever be narrowed, never widened past what the account itself may see. If someone shared a subset of their libraries with you, your own managed users can never see more than that subset.
Kid mode and rating limits
Kid mode gives that profile a simplified interface with larger tiles, and hides settings and statistics.
A rating ceiling blocks anything above it. Ratings are ranked, and unrated content is blocked whenever a ceiling is set, because unrated is where the surprises live.
| Rank | Ratings treated as equivalent |
|---|---|
| 1 | G, TV-Y, TV-G |
| 2 | PG, TV-Y7 |
| 3 | TV-PG |
| 4 | PG-13, TV-14 |
| 5 | R, TV-MA |
| 6 | NC-17, X |
Daily limits and bedtimes
A managed profile can have a daily watch limit in minutes and a bedtime window. Both are enforced by the server on every playback request, so switching device or app does not get around them.
The daily limit counts real time watched, taken from the same ledger that feeds the statistics page. It is not the sum of runtimes, so abandoning a film after ten minutes costs ten minutes.
How bedtime handles midnight
A bedtime window is a start time and an end time. When the start is earlier than the end, the window is the obvious range. When the start is later than the end, the window wraps past midnight.
bedtime 20:00 to 22:00
blocked between 8 PM and 10 PM, same evening
bedtime 21:00 to 07:00
start is after end, so the window wraps:
blocked from 9 PM through midnight and on until 7 AM
In code that is a single comparison. When start is less than or equal to end, the current time must fall inside the pair. Otherwise the current time must be at or after the start, or before the end. The second case is what makes an overnight window work.
Bonus time
The account owner can grant extra minutes on top of today's limit from the profile edit screen. Bonus minutes are recorded against today's date and are ignored tomorrow, so there is nothing to remember to undo.
What happens when a limit is reached
Playback that has already started is stopped at the next progress report, which is within about ten seconds, and the reason appears on screen. Starting something new is refused immediately with the same message. The watch time is still recorded, because the ledger is written before the check runs.
Playback
Direct play, direct stream, and converting
Every time you press play the server decides how to deliver the file. The player shows which one it chose, and Settings shows why in plain words.
| Mode | What happens | Cost |
|---|---|---|
| Direct play | The original file is sent untouched. | Almost none. This is the goal. |
| Direct stream | Video is copied as-is, audio and the container are rebuilt. | Small. Video is the expensive part and it is not being re-encoded. |
| Converting | Video is decoded and re-encoded. | Large. This is what makes a processor work hard. |
What qualifies for direct play
All three of these have to be true:
| Part | Accepted |
|---|---|
| Video codec | h264, vp8, vp9, av1. Also hevc when the browser proved it can decode it. |
| Audio codec | aac, mp3, opus, vorbis, flac |
| Container | mp4, mkv, webm, mov, m4v |
If the video codec is fine but something else is not, the result is direct stream. If the video codec itself is unsupported, the result is converting.
Chrome plays a file with DTS or E-AC3 audio silently. The video runs, the audio track is simply missing, and it looks like a broken speaker rather than a codec problem. Treating those as unsupported forces an audio rebuild, which costs very little and means sound always works.
Picking a quality forces conversion
Choosing 1080p, 720p or 480p in the player always converts, because resizing a picture requires decoding it. The presets are 1920 wide at 8 Mbps, 1280 at 4 Mbps, and 854 at 2 Mbps.
HEVC and 4K
The browser tests whether it can hardware decode HEVC and tells the server. If it can, a 4K HEVC file is stream copied instead of re-encoded. On an 80 GB remux that is the difference between a modest network transfer and a processor at full load for two hours.
Copied HEVC is tagged hvc1 inside the output container, because browsers reject the alternative tag.
The fallback that makes odd files work
If a direct or direct stream playback errors part way through, the player restarts the same moment as a full conversion and shows a short message. This catches 10 bit H.264, damaged containers, and files whose metadata claims a codec they do not actually contain.
The practical effect is that if ffmpeg can decode it, it plays. Conversion also forces 8 bit output, deinterlaces frames that are flagged as interlaced, and allows a large probe window so unusual Matroska files are read correctly.
Audio tracks
Files with more than one audio track show a track list in the player's settings menu. Picking a track that is not the first one forces at least a direct stream, because browsers cannot switch audio tracks by themselves.
Subtitles
Three sources are used, in this order:
- Embedded text tracks inside the file. Recognised formats are SRT, SubRip, ASS, SSA, mov_text, WebVTT and VTT.
- Sidecar files next to the media file, with extensions
.srt,.ass,.ssa,.vttor.sub. - Downloaded from OpenSubtitles, if you set an API key in Settings.
PGS and VobSub are pictures rather than text. They cannot be turned into browser subtitles without optical character recognition, so they are not listed. Use a sidecar file or generate one.
Generated subtitles
Movies and episodes have a Generate subtitles button. It extracts a small mono audio file, sends it to a Kinode Transcripts server, and writes the result back as an .srt beside the media file. Configure the engine URL and key under Settings, Maintenance.
With nightly captioning enabled, up to three recent additions that have no subtitles are captioned at 4 AM.
Remembered language
The subtitle track you pick is remembered per show and per profile. The next episode selects the same language without asking.
Casting
The web player casts through the browser's own remote playback machinery, so there is no Google SDK on the page and nothing leaves your network. Chrome and Edge offer the cast button. When a television connects, the player switches to a converted stream the receiver is known to handle rather than sending whatever the browser happened to be playing, and any subtitle you pick is burned into the picture, because the stock receiver does not render separate subtitle tracks dependably. The music bar casts too, and sends the original files, which the receiver plays natively. Live channels can be cast as well; that path is the newest and the least proven.
Two limits worth knowing. A cast stream is a conversion that starts at the point you resumed from, so the television's own clock counts from there rather than from the start of the film; the position shown in the player is the real one. And casting a download sends the server's copy, because the television cannot reach a file stored on a phone, which makes downloads phone-only when the server is unreachable.
Seek preview images
Hovering the seek bar shows a frame from that point. A background job builds one image strip per file using keyframes only, one file at a time, and caches it permanently. The first time you hover a file it queues the job, so previews appear on the next play rather than immediately.
Equalizer and normalization
Both live behind the equalizer button in the player and the music bar, and both apply live. Dragging a slider changes the sound immediately with no restart.
- Ten band equalizer from 31 Hz to 16 kHz, plus or minus 12 dB. Presets are Flat, Dialogue, Bass boost, Treble boost and Less bass. You can save your own named curves.
- Audio normalization is a compressor that evens out films where dialogue whispers and explosions do not. One toggle.
Settings are saved per profile. Custom equalizer presets are shared across the profiles on one account.
Accessibility and TV mode
The accessibility panel is reachable from the top bar and from the who-is-watching screen. It offers interface size, subtitle size, a solid subtitle background, high contrast, and reduced motion. The system setting for reduced motion is respected whether or not the toggle is on.
TV mode makes everything larger, adds strong focus outlines, and turns on arrow key navigation across the whole interface with Enter to select. That makes any browser on a television or a console usable from a sofa with a keyboard or a remote.
Music
Music libraries browse as artists, then albums, then tracks. Playback uses a bar along the bottom of the window, so browsing does not interrupt what is playing. Starting a video pauses the music and the reverse is also true. Operating system media keys work through the Media Session API, so the play button on a keyboard, a headset or a lock screen does what you expect.
How music is filed
The scan reads the tags inside each file first and only falls back to folder names when a file has none. That includes Ogg and Opus files, whose tags live in a different place from MP3 and FLAC.
- Album artist decides which artist an album sits under. A guest singer on one track is shown on that track rather than creating a second artist.
- Compilations, meaning files tagged as a compilation, are kept together under one album artist, Various Artists by default. Both the behaviour and the name are in Settings, Music, Library.
- Disc numbers are honoured, so a two disc album plays disc one in order and then disc two.
- Sort tags such as an album artist sort of "Beatles, The" decide where an artist appears in the list.
Formats and sound quality
Files play untouched whenever the device can play them, which in most browsers means MP3, AAC and M4A, FLAC, Ogg, Opus and WAV. Anything else, such as WMA, APE, WavPack, Musepack, DSD or AIFF, is converted by the server as it plays, so every file in the library works on every device. Converted copies are kept for a while so a second play starts at once. The format, quality, channels and the space set aside for converted copies are in Settings, Music, Converting.
Each listener can also choose a lower quality for themselves in Preferences, Music, which is handy on a phone plan. Owners can set a separate quality for listening away from home.
Tracks show a small badge for their sound quality: Lossless for FLAC, ALAC, WAV and similar, and Hi-Res when a lossless file is above 16 bit or 48 kHz. The full Now Playing screen spells it out, for example 24-bit / 96 kHz FLAC.
Now Playing and the queue
Select the album art in the music bar to open the full Now Playing screen, with large artwork, the controls, lyrics and the queue side by side. Space plays and pauses, the arrow keys jump ten seconds, L switches to lyrics and Esc closes it.
The queue can be edited while music plays. Any track menu offers Play next and Add to queue, rows can be dragged into a new order or moved with Alt and the up and down arrows, and Delete removes one. The queue can be cleared or saved as a playlist in one go. It is remembered per profile, so reloading the page or coming back tomorrow puts it back, paused where you left it.
Gapless playback and crossfade are in Preferences, Music. Crossfade leaves alone the tracks of one album played in order, so a live record or a continuous mix still runs straight through. That can be switched off in the same place.
The moon button in the music bar is a sleep timer. Choose a number of minutes or the end of the current track, and the music fades out over the last few seconds.
The Android app and Google TV app carry on through an album to the next track by themselves, and they ask the server to convert any file they cannot play.
Playlists
Playlists are per profile and appear in the sidebar. Add a single track, a whole album or an artist's entire catalogue from any menu. A playlist page can play, shuffle, rename, give it a description, reorder by dragging, duplicate, export and delete. Its cover is a mosaic of the first four albums in it.
Import a playlist in the sidebar reads an .m3u or .m3u8 file from another player. Tracks are matched by their file path first and then by artist and title, and the result tells you how many were found and how many are not in your library. Export writes the same format back out.
Liked songs and mixes
The heart on any track adds it to Liked songs, which has its own page in the sidebar. Hearts belong to each profile.
A music library opens with a row of mixes made from your own listening: Liked songs, Most played, Recently played, Recently added, Forgotten favourites, Never played and a shuffle of the whole library. They update as you listen, and nothing about your listening leaves the server to make them. Their length and what counts as forgotten are in Settings, Music, Mixes.
Artist pages
An artist page shows the photo and biography, the artist's most played tracks, their albums, and albums by others that they appear on.
Lyrics
The lyrics button and the Lyrics tab of Now Playing look in this order:
- An
.lrcfile next to the audio file, shown in time with the music. A plain.txtfile with the same base name is shown as static text. - Lyrics stored inside the file itself, which many taggers write.
- LRCLIB, a free and open lyrics database. Only the artist, title, album and length of the track are sent. Turn this off in Settings, Music, Lyrics if you would rather nothing is looked up.
Synced lyrics highlight the current line, and selecting any line jumps to it. Lyrics found online are kept by the server, and can also be saved next to the music as .lrc files if you want other players to use them. Owners can correct lyrics from the lyrics panel, including stamping each line with the current time to sync plain text, and can ask for a fresh search.
Audiobooks and long audio
Anything longer than fifteen minutes resumes where that profile stopped rather than starting over, and appears in Continue Watching. Ordinary songs never do. The music bar has a speed control that cycles through 1x, 1.25x, 1.5x, 2x and 0.75x.
Volume leveling
Leveling brings tracks to a common loudness, so a quiet rip and a loud master do not make you reach for the volume. Switch it on with Level music volume in the accessibility panel. If a file carries ReplayGain tags they are used straight away. Otherwise each track gets a loudness measurement in the background the first time it is played.
Leveling can work per track, per album, or automatically, which uses album leveling while an album plays in order and track leveling for shuffles and playlists. Album leveling keeps a quiet ballad quiet next to the loud songs around it, as it was mastered. The target loudness, the largest boost allowed, and protection against boosting into distortion are in Settings, Music, Volume leveling. Each listener can pick the mode for themselves in Preferences, Music.
Radio
The radio button builds an endless queue from any track, seeded by the artist first and then filled from the rest of that library. It uses your own files, and no external service is involved. Switch on Keep playing when the queue ends in Preferences, Music and radio starts by itself from the last track when an album or playlist finishes.
ListenBrainz
Kinode can send what you listen to to ListenBrainz, the open listening history service run by MetaBrainz. Paste your user token into Preferences, Music. Kinode checks it, then records a listen once you have heard half of a track or four minutes of it, and shows what is playing now on your profile. Each profile has its own token, nothing is sent until one is added, and removing it stops sending at once. The owner can switch the feature off for the whole server in Settings, Music, Scrobbling.
Remote access
How the directory works
Your server sends the hub a heartbeat every 30 seconds. That heartbeat carries a machine identifier, a shared secret, the friendly name, the port, whether HTTPS is ready, and a list of addresses where the server can be reached.
When an app signs in, the hub returns each server the account owns or has been shared, with a list of candidate addresses and an access token. The app tries the addresses in order and uses whichever answers.
Access tokens are signed with your server's own secret, which the hub holds a copy of from registration. Your server verifies them itself, without asking the hub anything. That is why playback continues to work when the hub is down.
Why local addresses are tried first
The candidate list puts private network addresses ahead of the public one. When your phone is on your own wifi it talks to the server directly across the local network, which is faster and does not touch your internet connection at all. The public address is used only when the local ones do not answer.
Making it reachable from outside
Two things are needed. The firewall rule, which the installer created, and a port forward on your router, which you have to do yourself.
- Give the machine running the server a fixed local address, either a static address or a DHCP reservation on the router.
- In the router's admin page, forward external TCP port 5466 to that machine's port 5466.
- Wait for the next heartbeat, which is within 30 seconds.
Your server cannot see its own public address from behind a router, so the hub fills it in. The address a heartbeat arrives from is the public address, and the hub records it and hands it back as a candidate.
HTTPS, automatically
A server connected to the hub gets real HTTPS with no setup. The hub gives every server DNS names of the form <address>.<server-id>.s.kinode.tv, one per address it has, local ones included, and issues a trusted certificate covering all of them. The server picks the certificate up over its existing authenticated connection and serves HTTPS on the same port as HTTP: the first byte of each connection says which protocol it is, so the port forward you already made keeps working and nothing new is opened.
Apps and the web player prefer the padlocked addresses automatically. Certificates renew on their own about a month before expiry. If your network's router blocks DNS answers that point at private addresses ("DNS rebind protection"), local connections quietly fall back to plain HTTP inside your own network while remote ones stay encrypted. Allow-listing s.kinode.tv in the router's rebind settings restores the padlock at home too.
Setting your own public address
If you have a domain, dynamic DNS, or a reverse proxy with a certificate, put the full address into Settings, Maintenance, Public address. For example https://media.example.com. That takes priority over the address the hub infers, and over the generated names above, for people who prefer their own name on the box.
Apps
The web app
The fastest way in is Open the web player on the kinode.tv home page. Signed in, it checks which of your server's addresses answers from the network you are on, preferring the local one, and sends you straight to the player. Signed out, it asks you to sign in first and then completes the trip. If no address answers, you land on your account page instead, where every reported address is listed as a link so you can try them yourself.
The browser interface is installable. Chrome and Edge offer an install button in the address bar, which gives it a window without browser furniture and its own icon. A small service worker caches the interface so it opens even if the server is briefly unavailable, though playback obviously needs the server.
Android
- Casting. A cast button appears when a Chromecast is on the network. The television takes over and the phone becomes the remote: play, pause, seek, volume and stop drive the TV, a notification keeps those controls available outside the app, and episodes roll into the next one on the television. Stopping the cast hands the position back to the phone.
- Downloads. Long press any movie or episode and choose Original, 1080p or 720p. Downloads are stored in app private storage with their artwork, and the Downloads screen plays them with no server involved. Watch progress is queued locally and sent to the server the next time it is reachable. Casting a download plays the server's copy of the same title, because the television cannot read a file stored on the phone; without the server, downloads are phone-only.
- Remote. Lists players across every server on the account and drives them with play, pause, seek, next, previous and stop.
Casting converts on the way out. The Android app hands the television its converted stream, and the web player switches to one when a remote screen connects. Chromecast support for Matroska, DTS and high-bit-depth video is inconsistent, so the reliable path is used deliberately, and in the web player any chosen subtitle is burned into the picture while casting.
Roku
The Roku channel is sideloaded rather than published. Enable developer mode on the Roku, browse to its address, and upload the zip.
It has the who-is-watching screen with PIN entry, sends the profile with every request so watch history is correct, and can be driven from the Remote screen in the Android app. Next and previous are ignored on Roku because it has no episode queue yet.
Discord bot
The bot is optional and runs next to the server. It needs a Discord application of your own, because a bot token identifies your bot and cannot be shared.
Commands
| Command | What it does |
|---|---|
/nowplaying | What is streaming right now, with who is watching and whether it is converting. |
/search | Search the library from Discord. |
/stats | Watch time across the household, library size, data served. |
/server | Health checks and drive space. |
/request | Ask for something to be added. Goes into the request queue and triggers automation if it is set up. |
/bug | File a bug on the tracker. |
/bugs | List bugs, optionally filtered by status. |
/play | Play a track, an album or an artist in your voice channel. |
/playlist | Play a playlist from the server. |
/nowqueue | What is lined up. |
/skip /pause /stop | Transport controls. |
/watch | Start a watch party and post the join code. |
/queue /triage /review | Staff commands for reports, bug status and plugin review. |
Channels it creates
Calling POST /bot/setup once creates seven channels and returns their identifiers to paste into the configuration:
| Channel | Carries |
|---|---|
kinode-announcements | New episodes, new arrivals, the weekly recap |
kinode-requests | Requests, and a message when one is ready |
kinode-alerts | Disk space warnings |
kinode-activity | What is playing |
kinode-bugs | Bug intake |
kinode-bug-log | New bug notifications for whoever is fixing them |
kinode-moderation | Reports and plugin reviews |
Bug intake threads
Anything said in the bugs channel becomes a bug on the tracker. The bot replies with the number and opens a thread underneath. From then on that thread and the bug are the same conversation: messages in the thread become comments on the bug, and staff replies on the website are pushed back into the thread.
Severity is guessed from the wording. Words like crash, data loss and cannot sign in read as critical. Broken, error and hangs read as high. Typo, cosmetic and occasionally read as low. You can always override it.
The link between a Discord thread and a bug is held in memory. Restarting the bot means older threads stop mirroring. That is deliberate, because persisting the mapping risks a stale identifier routing a comment onto the wrong bug. New threads work normally.
Music in voice channels
The bot streams from your library into a voice channel. It does not use Lavalink or any other external audio service. The server converts the track to Ogg Opus, which Discord voice plays directly, so there is no Java process and no native audio module to compile.
The player message has album art, a progress bar, and buttons for back, pause, skip, stop, shuffle, loop and queue, plus a radio button that extends the queue with similar music.
Rich Presence
Showing what you are watching on your own Discord profile is a separate program called presence.js, and it has to be. Discord only allows an application to set its own status, so a bot can never write to your profile. Rich Presence works over a local socket that the Discord desktop client opens on your machine, which means the program has to run on your machine next to Discord.
It reads what you are playing from your server, and writes it to your profile with artwork, a live progress bar and a paused state. There is a private mode that keeps it running without showing anything. Nothing leaves your network.
The bot itself shows a server wide status instead, naming what is playing when one thing is, or a count when several are.
Plugins
The shape of a plugin
A plugin is a folder holding a manifest and up to two scripts. Both scripts are optional, so a plugin can add only a home row, only a panel on an item page, only an endpoint, or any combination.
on-this-day\
plugin.json required
server.js optional, runs in the server process
client.js optional, runs in the web app
{
"id": "on-this-day",
"name": "On This Day",
"version": "1.0.0",
"author": "you",
"description": "One or two sentences.",
"homepage": "https://github.com/you/on-this-day",
"permissions": ["library:read", "ui:home", "storage"],
"server": "server.js",
"client": "client.js",
"settings": [
{ "key": "minYears", "label": "Only films this old", "type": "number", "default": 5 }
]
}
The identifier must be lowercase letters, numbers and dashes, and it must match the folder name. Anything listed under settings becomes a form on the owner's plugin page, and whatever they save arrives as plugin.config.
Permissions
A plugin asks for what it needs. The owner sees the list in plain words before enabling it, and a permission that was not requested is simply absent from the object the plugin receives.
| Permission | Grants |
|---|---|
library:read | Look up libraries, items, search, random picks, recently added, genres. |
playback:events | Hear when something is played or finished. |
ui:home | Contribute a row to the home page. |
ui:detail | Contribute a panel to movie and show pages. |
http:routes | Expose endpoints under /api/plugins/<id>/. |
schedule | Run a function on an interval, never faster than once a minute. |
notify | Send a message through the server's notification channel. |
network | Reach the internet. |
logs:read | Read this server's own log files. |
server:control | Start scans and metadata passes, correct a wrong match, rebuild collections, and fetch lyrics and subtitles. Nothing here deletes media. |
storage | Key and value storage. Always granted, listed so the owner sees it. |
A server plugin is JavaScript running inside the media server process, the same as any dependency the server installs. The permission list shapes the API a plugin receives and tells the owner what to expect. It is not a sandbox, and it does not stop determined code from doing anything the runtime can do.
That is the same arrangement as Plex channels, Jellyfin plugins and browser extensions. Install plugins you trust, and read the source when you can. Review before listing here is a check on obvious problems, and it is not a security guarantee.
The server half
module.exports = {
async setup(plugin) {
// library:read
plugin.library.libraries();
plugin.library.item(1234);
plugin.library.search('blade runner', 20);
plugin.library.format(item);
// ui:home, return null and nothing renders
plugin.homeRow('key', (ctx) => {
return { title: 'A row title', items: [ /* items */ ] };
});
// http:routes, reachable at /api/plugins/<your-id>/thing
plugin.route('get', 'thing', (req, res) => res.json({ ok: true }));
// playback:events
plugin.on('playback:finished', (info) => {});
// schedule
plugin.every('30m', async () => {});
// storage, survives restarts
plugin.storage.set('cursor', 42);
plugin.storage.get('cursor', 0);
},
async teardown() {}
};
Home rows have a four second budget. A row that takes longer is skipped for that page load, so a slow plugin cannot stall the home page.
The browser half
plugin.onDetail((item, mount) => {
const el = document.createElement('div');
el.className = 'panel-card';
el.textContent = item.title + ' came out in ' + item.year;
mount.appendChild(el);
});
const data = await (await plugin.api('thing')).json();
plugin.ui.card(item);
plugin.ui.play(itemId);
plugin.toast('done');
Client code is wrapped in a try and catch by the host, so a mistake logs an error rather than breaking the page.
Installing and publishing
While writing one, drop the folder into the server's data\plugins\ directory. It appears in Settings, Plugins, turned off. Turning it on starts it, and saving its settings reloads it, which is the fastest way to pick up code changes without restarting the server.
To share it, zip the folder so that plugin.json sits at the archive root or inside a single folder named for the plugin, publish the zip at an HTTPS address, and submit it on the plugins page.
Every submission is reviewed before it is listed, and a new version of an approved plugin returns to pending. That prevents an approved listing being swapped for different code after review.
Automation
Requests can be wired to Radarr, Sonarr and Lidarr so that asking for something starts the process of getting it.
| Request type | Service | API | Matched on |
|---|---|---|---|
| movie | Radarr | /api/v3 | tmdbId |
| show | Sonarr | /api/v3 | tvdbId |
| music | Lidarr | /api/v1 | foreignArtistId |
Set each service's address and API key under Settings, Maintenance. The first quality profile and the first root folder are used, so make sure the ones you want are first in each service.
What happens to a request
- Someone asks for a title and marks it as a movie, show or music.
- The matching service is asked to look the title up, and the first result is added as monitored with a search started immediately.
- Every five minutes the download queue is checked. The request shows searching, then downloading with a percentage.
- When the file lands, the request flips to done and a notification is posted.
An owner can also send any request to a service by hand from the requests inbox. Subtitles are handled by the built in captioning, so Bazarr is not needed.
Owner tools and maintenance
The health panel
Settings, Maintenance shows a list of checks with plain verdicts. It covers the library database, the transcoder binary, whether a hardware encoder was found, the scanner binary, the hub connection with the age of the last heartbeat, remote access, the notification webhook, the captioning key, background queue depths, and free space on every drive holding a library.
Backups
Settings, Maintenance has a Download backup button. It downloads one recovery archive, a file ending in .kinode-backup, that holds the library database, accounts, profiles, PINs, watch history, playlists, ratings, comments, requests, settings, the signing key and plugin settings. Media files, artwork caches and plugin code are not in it. Keep the file private, because it contains passwords and access keys.
The server also takes a snapshot of its own each time it starts. Snapshots go in the backups folder inside the data directory, and the newest five are kept.
To restore, open PowerShell in the application folder and check the archive first:
.\node.exe tools/restore-backup.js --validate "backup.kinode-backup"
Then stop the server and restore it, using your own data folder in place of the one shown:
.\node.exe tools/restore-backup.js --restore "backup.kinode-backup" --data-dir "C:\ProgramData\Kinode Media Server" --stopped
The tool checks both databases, keeps the previous state, and rolls back if the restore fails. The same steps are under Show restore instructions in Settings, Maintenance. Your media files are not in the backup because they are not the server's to hold. Plugin code is not in it either, so review and enable plugins afterwards.
Library audit and reclaim
Settings, Library audit runs four checks and offers a reclaim list:
- Duplicate versions, meaning one film with more than one file.
- Below 720p, sorted by height.
- Season gaps, listing shows that have episode 1 through 4 and then 6.
- Movies with no subtitles of any kind, embedded or sidecar.
- Reclaim, listing large files that were watched, rated low, or untouched for a year, ranked by space returned.
Nothing is deleted for you. The list is a starting point and the decisions are yours.
Notifications and the weekly digest
Set a Discord webhook, or the bot, under Settings, Maintenance. The server then sends:
- New episodes of shows you followed.
- Newly added films and series.
- A recap on Sunday evening with hours watched, the most watched title, per person leaders and data served.
- One warning per day for any library drive above 90 percent full.
- Movie night reminders an hour before and at the start.
Statistics
Every profile has a statistics page with hours watched, plays, titles, a thirty day chart, a time of day histogram, a playback mode breakdown, most watched, recently watched and a year to date summary.
Hours are real time watched. The server adds the gap between progress reports, capped at sixty seconds so a laptop waking from sleep cannot bank hours it did not play. Runtimes are never summed, so abandoning a film after ten minutes counts as ten minutes.
Owners additionally see server wide totals, a usage calendar, and a live monitor with processor load, memory, streaming bandwidth counted at the byte level, and free space per drive.
Hub accounts, passwords and recovery
Accounts on this website are separate from accounts on your server. There are four ways back into a hub account:
- Change your password while signed in.
- Recovery codes. Eight single use codes, shown once when you register, stored as hashes. They need no email and no administrator.
- A reset link by email, sent to the address on your account.
- An administrator generated link, for when the other three fail.
For your own server, a forgotten password is fixed on the machine itself:
cd "C:\Program Files\Kinode Media Server\app"
node tools\reset-password.js lists the accounts
node tools\reset-password.js owner sets a generated password
node tools\reset-password.js owner mypass sets one you choose
Troubleshooting
Symptoms first, then the causes worth checking in the order worth checking them.
The page will not load at all
Check the service and start it if it is stopped.
sc query KinodeMediaServer
net start KinodeMediaServerOn the machine itself use http://localhost:5466. From another device use the machine's local address, for example http://192.168.1.20:5466. Older builds used 32402, so an old bookmark will fail.
Read the log, which is the fastest way to a real answer.
type "C:\ProgramData\Kinode Media Server\logs\KinodeMediaServer.err.log"The service will not start
See the next entry. This is the most common cause.
The service runs as Local System and needs to write to C:\ProgramData\Kinode Media Server. If that folder was moved or its permissions were changed, the server cannot create its database or its signing key. Recreate the folder and allow Users to modify it.
Stop the service and use the Start Kinode Media Server.cmd shortcut. Errors that a service swallows are printed in the console.
Port already in use
netstat -ano | findstr :5466
tasklist /fi "pid eq 1234"
The first command prints the process identifier in the last column. The second names it.
Edit kinode-service.xml in the install folder, change the PORT value, then reinstall the service and add a firewall rule for the new port.
net stop KinodeMediaServer
"C:\Program Files\Kinode Media Server\kinode-service.exe" uninstall
"C:\Program Files\Kinode Media Server\kinode-service.exe" install
net start KinodeMediaServer
netsh advfirewall firewall add rule name="Kinode Media Server" ^
dir=in action=allow protocol=TCP localport=5500 profile=private,domainAn older instance started from a console window keeps the port. Close that window, or end the node.exe process holding the port.
It works on the server but not from other devices
Add the rules by hand in an administrator command prompt.
netsh advfirewall firewall add rule name="Kinode Media Server" ^
dir=in action=allow protocol=TCP localport=5466 profile=private,domain
netsh advfirewall firewall add rule name="Kinode Media Server discovery" ^
dir=in action=allow protocol=UDP localport=5467 profile=private,domainThe rules only apply to private and domain networks. Open Settings, Network, and set the connection to Private. This is common after a router change, because Windows treats the reconnected network as new.
Some routers, and most guest networks, stop devices talking to each other. If a phone on wifi cannot reach a server on ethernet, check for a setting called AP isolation or client isolation and turn it off.
Some suites replace the Windows firewall entirely, and netsh rules mean nothing to them. Add the rule in that product's own interface.
Video plays but there is no sound
Browsers cannot decode these. Chrome plays the file with silence rather than reporting an error, which is why it looks like a speaker problem. The server treats these as unsupported so audio is rebuilt automatically, and the mode tag will say Direct Stream rather than Direct Play.
If it is still silent, the file was probably forced to Direct Play. Turn Auto Convert back on in the player's settings menu.
Files with several tracks sometimes default to a commentary or a foreign language track. Open the player settings menu and pick another under Audio.
Worth ruling out. Right click the tab and check.
Everything converts when it should direct play
Choosing 1080p, 720p or 480p always converts, because resizing requires decoding. Set quality back to Original.
This is the usual answer. The video is fine and the audio forces a rebuild, which shows as Direct Stream. The cost is small and it is not worth avoiding.
Safari and recent Edge handle HEVC. Firefox generally does not. Chrome depends on the machine. When the browser cannot prove it decodes HEVC, the server converts, which is expensive on 4K.
Play 4K HEVC in a browser that supports it, or use the Android app.
The player names the actual cause, for example that the audio is DTS or the container is AVI. Settings, Activity shows the same reason for every running stream.
Buffering or stuttering
Settings, Activity shows how many streams are converting. Software conversion of 4K in real time needs a strong processor, and two at once needs a very strong one. Pick a lower quality, or store a version the client can direct play.
The health panel says whether one was found. The bundled ffmpeg uses the processor, which is slower than a graphics card would be. This is a known limitation of the current build.
A 4K remux can exceed 80 Mbps sustained, which is more than many wireless links deliver reliably. Test with a wired device to separate a network problem from a server problem.
Several streams from one mechanical drive, or a network share, can starve playback while the processor looks idle.
Seeking is slow on converted video
A converted stream is a live pipe out of ffmpeg. There is no file to jump around inside. Seeking kills the pipe, restarts ffmpeg at the target second, and resumes, so there is a pause of a second or two.
Direct play seeks instantly, because the browser is reading a real file. Another reason to prefer files that direct play.
Subtitles are missing or out of sync
PGS and VobSub are pictures and cannot be displayed as browser subtitles. They are not listed at all. Use a sidecar file or the Generate subtitles button.
A sidecar has to share the base name of the media file and sit in the same folder.
Blade Runner (1982).mkv
Blade Runner (1982).srt works
Blade Runner (1982).en.srt works
subs\Blade Runner.srt not foundSubtitle timings are absolute while a restarted conversion resets the clock to zero. The server shifts the subtitle file to compensate on each restart. If they are still wrong, pause and resume to force a refresh.
Then the file itself is mistimed, usually because it was made for a different release. Download another one from the subtitle search in the player.
It plays on the phone but the TV errors immediately
The automatic HTTPS names are public DNS names that resolve to addresses inside your network, and many routers refuse DNS answers shaped like that, a feature called DNS rebind protection. The phone already knows the answer and plays; the television asks the router, gets nothing back, and gives up. The Android app picks the plain http local address for the television exactly to sidestep this, so casting usually works regardless. This entry is for when it does not.
The clean fix is an exception on the router: on dnsmasq or OpenWrt, rebind-domain-ok=/s.kinode.tv/, or add s.kinode.tv to list rebind_domain. First to third generation Chromecast dongles ignore the router's DNS entirely and ask 8.8.8.8 directly, so those also need outbound UDP port 53 to 8.8.8.8 allowed.
No artwork, or the wrong artwork
Titles appear before posters. Give a large library some time after the first scan.
Wrong poster nearly always means wrong match, especially for remakes. Rename to Title (Year).ext and rescan.
If every item shows a generic icon, artwork is failing to load rather than failing to match. Open the browser console and look for failing image requests.
A scan finds nothing
The library's Edit window lists each folder with what it found there. If a folder says it is empty, the media is somewhere else. Use Browse for a folder to pick the right one.
A service runs as Local System, which has no access to mapped network drives created by your user account. Use a UNC path such as \\nas\media, or run the server in a window under your own account to test.
A TV library pointed at a folder of loose films finds nothing, because it expects show and season directories.
Remote access does not work
The firewall rule is not enough. The router has to forward external 5466 to the machine. Verify from a phone on mobile data rather than wifi, because a phone on your own wifi will succeed for the wrong reason.
DHCP hands out a different address after a reboot and the forward now points at nothing. Give the machine a reservation on the router.
Heartbeats are every 30 seconds, and one is sent a few seconds after the server starts. The health panel shows the age of the last successful one.
Some internet providers, and most mobile broadband, do not give you a real public address. Port forwarding cannot work at all in that case. Ask your provider about a public address, or use a tunnel service.
A router behind another router means the forward has to exist on both. The symptom is a forward that looks correct and does nothing.
Cannot sign in to a server
Server accounts and hub accounts are separate. The hub account signs in at kinode.tv. The server account signs in at your server's own address.
Reset it on the machine.
cd "C:\Program Files\Kinode Media Server\app"
node tools\reset-password.js
With no arguments it lists the accounts. With a username it sets a new password and prints it.
Sign in tokens are signed with a key stored at data\secret.key. If that file is deleted or the data directory moved, every existing token becomes invalid and everyone signs in again. Nothing else is lost. Changing an account's password also signs that account out on its other devices.
A managed user sees the wrong libraries
Editing a managed user offers everything on the server, or a specific list. If the first is ticked, the list underneath is ignored.
A profile can never see more than the account it belongs to. If your access was shared to you as a subset, your managed users are bounded by that subset regardless of their own list.
Switch profile and back, or reload. Clients remember the profile they last used.
The Discord bot is offline
Resetting a bot token in the developer portal invalidates the old one immediately. The error is explicit about an invalid token.
The bug intake channel needs it. Without it, the bot connects and sees empty message bodies. Enable it under Bot, Privileged Gateway Intents.
With a guild identifier set they register immediately. Registered globally they take up to an hour. Set DISCORD_GUILD_ID.
Use the Test button in Settings, Maintenance. It calls the bot's ping endpoint and reports what answered.
The bot must be able to join and speak in the voice channel, and you have to be in one when you ask.
Email is not arriving
Two real failures that are worth knowing about, because both were hit in practice and neither is obvious.
This happens when the sending address belongs to a domain that has not authorised the sending service. A message claiming to be from a Gmail address, signed by Amazon, is exactly the shape of a phishing attempt and filters treat it that way.
The fix is to send from a domain you control and have verified with the mail provider, so the address in the From line and the signature agree.
A systemd unit splits Environment= values on whitespace unless they are quoted. Configuring a sender as Kinode Media Server <[email protected]> without quotes delivers the single word Kinode to the program, the mail provider rejects it as an invalid address, and a catch block swallows the error so nothing appears anywhere.
Environment=MAIL_FROM=Kinode Media Server <[email protected]>
Environment="MAIL_FROM=Kinode Media Server <[email protected]>"
The first line is wrong and the second is right. The lesson generalises: swallowing an error is right for the request and wrong for the operator, so every send is now logged with its identifier or its real error.
A mail provider in sandbox or trial mode delivers only to addresses that have been verified in advance. Everyone else silently receives nothing. Check whether production access has been granted.
A plugin will not load
The folder has to be named exactly as id in the manifest. This is checked and refused.
A trailing comma is the usual culprit. The plugin list shows the reason next to the plugin.
The plugin is disabled and the message is shown. Read the server log for the stack.
Check the permissions in its manifest. A plugin that did not ask for ui:home has its home rows quietly ignored, and the log says so.
Saving its settings reloads it. That is quicker than restarting the server.
A drive is full
Settings, Library audit lists large files that were watched, rated low, or untouched for a year, ranked by space returned.
Seek preview images live in data\trickplay\ and downloaded subtitles in data\subtitles\. Both are safe to delete, and both rebuild when needed.
Converted streams write segments to a folder named mc-hls in the temporary directory of the account the server runs as. A stream's folder is deleted when the stream stops, a stream nobody touched for five minutes is stopped and cleaned up, and anything a crash left behind is swept when the server starts and every ten minutes after that. When that drive has less than 1 GB free, new conversions are refused with a message until space is freed.
Any library drive above 90 percent full triggers one notification per day, if a webhook or bot is configured.
Glossary
- Attached mode
- Running against an existing library database and external binaries, configured through
engine.jsonorENGINE_*variables. - Bundled install
- What the installer produces. The runtime and a full ffmpeg ship inside, and nothing else needs to be present.
- Container
- The file format wrapping the audio and video, for example MKV or MP4. Separate from the codecs inside it.
- Direct play
- The original file is sent untouched. Cheapest for the server and best for seeking.
- Direct stream
- Video is copied as-is while audio or the container is rebuilt. Costs very little.
- Converting
- Video is decoded and re-encoded. The expensive one.
- Guest link
- A link to one title that works without an account and expires on its own.
- Hub
- This website. An account system and a directory for finding servers. It never handles video.
- Managed user
- A person on one server with a display name, an optional PIN, and their own watch history. No password, no email, and unknown to the hub.
- Owner
- The person who runs a server. The word admin is reserved for staff on this website.
- Part
- One physical file belonging to an item. A film with a 4K and a 1080p copy has two parts.
- Profile
- Another word for managed user, and the account owner counts as one.
- Remux
- Repackaging streams into a different container without re-encoding. What direct stream does.
- Sidecar
- A file beside the media file sharing its base name, most often a subtitle.
- Trickplay
- The preview images shown when hovering the seek bar.
- Watch together
- Synchronised playback in a room joined with a short code.
Questions people ask
Does any of this cost money?
No. There is no paid tier and no feature is held back. Remote streaming, hardware transcoding, sharing and everything else are included.
Do my files get uploaded anywhere?
No. Your media never leaves your machine except when you or someone you shared with streams it, and that connection is direct. What this website receives is a heartbeat with your server's name and addresses and, unless you turn off Fetch posters through the Kinode hub under Settings, Library, the title lookups your server makes for posters and descriptions.
Can you see what I watch?
No. Watch history lives in your server's database. The hub has no table for it and never receives it.
Do I need Plex installed?
No. Kinode has its own scanner and a complete ffmpeg is bundled, so it builds and plays a library on its own. If you also run Plex, the two can share a computer, and intro and credits markers can be imported from Plex.
Will it run on a Raspberry Pi or a NAS?
There are Linux builds for 64-bit Intel and AMD machines and for 64-bit ARM, as a .deb, a tarball and a Dockerfile. The x64 builds are tested. The ARM builds have not yet been run on real ARM hardware, so a Raspberry Pi 4 or 5 on a 64-bit system, or an ARM NAS, should work but is unproven. A NAS that runs 64-bit Linux with systemd can use the tarball. See Installing on Linux.
How many people can watch at once?
As many as your network allows when files play directly, because the server is only reading files. Converting is what limits you, and one 4K conversion can occupy a strong processor entirely.
Why is my processor busy when nobody is watching?
Background jobs. Seek previews, loudness measurement and subtitle generation all run one at a time when the server is idle. They finish and stop.
Can I move the server to a new machine?
Yes. Download a backup from Settings, Maintenance on the old machine, install Kinode on the new machine, stop it, and restore the backup with the recovery tool described under Backups. Accounts, profiles, watch history and the library come with it. Library paths have to point somewhere valid on the new machine.
Is my connection encrypted?
When the server is connected to the hub, remote connections use HTTPS with a certificate the hub issues for your server, on the same port you already forwarded. Local connections use HTTPS too, unless your router blocks DNS answers that point at private addresses, in which case they fall back to plain HTTP inside your own network. If you set your own public address, your own certificate is used instead. See HTTPS, automatically.
What happens if this website disappears?
Your server keeps working. The hub is a directory. Local access, playback, accounts and profiles are all local, and only finding your server from outside your house would need setting up another way.