Skip to content
ozankaraaliPublic

About

A cross-platform STB, Xtream, IPTV, Jellyfin and Emby player client

Topics

Resources

Stars

49 stars

Watchers

4 watching

Forks

Repository files navigation

QiTV - IPTV and STB Client

Please always download this free software from qitv.app, its website, or RELEASES instead of using others' distributions, which may have malware.

QiTV is a free TV player for IPTV. It plays M3U playlists (lists of channel links), Xtream accounts (a server address with a username and password) and STB portals (a set-top-box portal address and a MAC address), on Windows, macOS and Linux.

Version 2.0 works like a TV: the channel fills the window, ↑ and ↓ change channels, and everything else (the channel list, the guide, the player controls) slides in over the picture and gets out of the way again. You can pause and rewind live TV, watch two channels at once, and browse movies and series in a Library with posters. Since 2.1, several providers mix in one channel list, one Library and one history, and what plays keeps playing in a corner while you browse. It is written in Python with Qt and plays everything with VLC.

A live channel with the channel banner

All screenshots show demo content: the channels, programmes, posters and the test-pattern picture are made up by scripts/make_demo_content.py.

Installing

Download QiTV from RELEASES:

  • Windows: qitv-windows.exe. Run it; there is nothing to install. QiTV is not signed, so the first time Windows may say "Windows protected your PC": choose More info, then Run anyway.
  • macOS: qitv-macos-universal.dmg for Apple silicon Macs, qitv-macos-intel.dmg for Intel Macs. Open it and drag QiTV onto Applications (the same app also comes as a .zip). To update, Help → Check for Updates downloads the new .dmg, opens it and closes QiTV: drag QiTV onto Applications again and choose Replace. QiTV needs macOS 13 or newer. QiTV is not notarized by Apple, so the first time macOS may say it cannot check the app: open System Settings → Privacy & Security and choose Open Anyway.
  • Linux: qitv-linux. Make it runnable with chmod +x qitv-linux, then start it. QiTV needs glibc 2.38 or newer: Ubuntu 24.04, Debian 13, Fedora 39 or newer.

VLC comes inside QiTV: you do not need to install VLC to use it.

Linux Desktop Integration

After downloading the release binary or cloning the repo, you can install QiTV into your application menu so it persists across reboots:

Using the release binary:

chmod +x qitv-linux
git clone https://github.com/ozankaraali/QiTV/  # needed for install script and icon
cd QiTV
./scripts/install-linux.sh /path/to/qitv-linux

Using the source build (see Running from source):

./scripts/install-linux.sh

This installs a desktop entry and icon so QiTV appears in your application menu. The desktop entry uses absolute paths, so it works after rebooting without needing to re-activate the virtual environment.

Troubleshooting on Linux:

  • If the release binary does not start and says version `GLIBC_2.38' not found, your Linux is older than the libraries inside QiTV need (glibc 2.38: Ubuntu 24.04, Debian 13, Fedora 39 or newer). On an older one, run QiTV from source.
  • If the release binary fails with Qt/xcb plugin errors, install xcb-cursor: sudo apt install libxcb-cursor0 (Debian/Ubuntu) or sudo dnf install xcb-util-cursor (Fedora).
  • Make sure ~/.local/bin is in your PATH. Add export PATH="$HOME/.local/bin:$PATH" to your ~/.bashrc if needed.

Adding a provider

On a first start QiTV opens with a publicly available playlist of free channels from around the world, so you can try it straight away. To add your own provider:

  1. Press Enter (or click the picture) to open the channel list.

  2. Press ← until you reach the left-most column, the list of your sources (or click your provider's name at the top of the list). With two or more providers, All providers is at its top. At its bottom are ⚙ Settings, + Add provider, + Free channels… (iptv-org's free playlist again, for all countries or one country) and Open file (a video file on your computer, as Ctrl/⌘+O).

  3. Choose + Add provider. Settings opens on the Providers tab with a new provider to fill in:

    • M3U Playlist: the playlist's web address, or Load File for a playlist on your computer;
    • M3U Stream: the address of a single stream;
    • Xtream: the server address, your username and your password;
    • STB: the portal address and your MAC address (serial number and device ID only if your provider asks for them);
    • Jellyfin or Emby: your media server's address (for example http://192.168.1.20:8096), your username and your password. Verify Provider signs in; QiTV keeps the sign-in the server gives it, not your password (see Jellyfin and Emby).

    Got a single link from your provider? Copy it and press Paste link beside the address (or paste it into the address): an Xtream link with your username and password in it (get.php?username=…&password=… or player_api.php?…) fills in Xtream, the server, the username and the password; a playlist address ending in .m3u or .m3u8 fills in an M3U playlist; a portal address with /c/ or /stalker_portal/ in it fills in STB (add the MAC address yourself).

    You can also drop a playlist file (.m3u or .m3u8) or such a link onto the QiTV window: it becomes a provider and the channel list switches to it (a portal's link opens this form, for its MAC address). A subtitle file dropped at the same time still goes to what plays.

  4. Press Verify Provider to check the details, then Save. QiTV loads the channels, and the Library loads the provider's movies and series.

When a channel or a film doesn't open, or a provider can't be reached, QiTV asks the provider's account why (without opening a stream, at most once a minute) and says it in plain words: the subscription has expired, all the streams the account allows are in use ("Your account allows 1 stream; one is in use"), the username or password is wrong, the server refused or blocked QiTV, or it didn't answer. When QiTV's other picture is the one using the account's only stream, it says that instead. Verify Provider says the same: an expired, disabled or refused account doesn't verify, and a portal whose profile shows an end date in the past verifies with a note (some portals keep old dates).

If you delete every provider, including the free playlist, QiTV shows a welcome card whose Add provider button does the same; its Free channels… button adds iptv-org's free list again, for all countries or one country. Settings is one click away too: the ⚙ at the right end of the channel list's top row (beside it, ↻ loads your provider's channels and guide again, also Ctrl/⌘+R, ⌕ searches, and the clapperboard opens the Library at Movies or the section you opened last, as Ctrl/⌘+2; a provider's own Movies and Series rows open the Library on that provider), or the menu bar (Ctrl/⌘+,). The same row starts with ‹, which goes back a level like ←, and the names of where you are: click one to go there. To browse another provider, click your provider's name in that row and pick another in the sources column, or use the Providers menu. This only changes what the list shows: what plays keeps playing (see Several providers).

QiTV keeps each provider's lists for six hours and refreshes them in the background, so they open at once. If your provider allows only one or two streams at a time, QiTV never opens more: set Max simultaneous streams in the provider's settings when QiTV cannot read the limit from the provider. The limit counts per provider.

Several providers

With two or more providers, QiTV mixes them: every channel, film and series knows the provider it came from and always plays from there, whichever list you found it in.

  • All providers. The sources column (the channel list's left-most column) starts with All providers. It shows ★ Favorites, ⟲ Recent and All with every provider's channels together, each with its provider's name beside it, and then each provider's own groups under its name, named as that provider names them. Groups are never merged, even when two providers use the same name. Typed channel numbers find the first match, in the order of your providers in Settings.
  • Browsing is only browsing. Picking another provider, or All providers, only changes what the list shows: nothing that plays stops, picture-in-picture stays open, and ↑/↓ keep going through the list the channel was picked from. Enter (or a click on the picture) opens the list where the big picture's channel was picked: its provider, its group, its row.
  • Two providers at once. Watch a channel from one account and open one from another in picture-in-picture; swap them and change channels on either. Each provider's stream limit counts on its own, so two accounts that each allow one stream can each play one picture.
  • One history. ⟲ Recent lists the channels you watched at every provider, newest first, each with its provider's name. Right-click one there for Remove from Recents (or highlight it and press Delete), or Clear Recents to empty the list (also on ⟲ Recent itself). Backspace (the channel before) goes back across providers too, and Start with the last channel (Settings) tunes the last channel from its own provider.
  • The guide of a provider is loaded while its channels are on screen or playing, and let go afterwards, so All providers doesn't download every guide at once.
  • One account's trouble stays with it. A provider that can't sign in or refresh keeps its saved lists, and the other providers keep working. A channel you play from it says which provider failed and why.
  • The Providers menu in the menu bar lists your providers with All providers at the top, and ticks the one the channel list shows.

The channel list and the Library each remember the provider (or All providers) you browsed last, also after a restart. With a single provider there is no All providers row, and everything works as before.

Watching TV

Use the arrow keys like a TV remote: ↑ and ↓ change the channel, numbers jump to a channel, Backspace goes back to the channel before, and Enter opens the channel list. Each change shows a banner with the channel, what is on now and what is next. Hold the key (or press it quickly a few times) and a fast list of the channels around you opens; QiTV tunes the one you stop on.

The fast-zap list while changing channels

The channel list has your groups (with ★ Favorites and Recent at the top) on the left and their channels on the right, each with what is on now. To find a genre or a channel, type its name (or click ⌕ Find above the channels first): the matching genres come first, then the channels, from every provider (with two or more, each says which provider it is from): whole words before parts of words, then the provider you are browsing or watched last, then your favorites. Click or press Enter to open a genre or play a channel; the last row looks for films and series with those words in the Library. Esc or ✕ takes the list back to where it was. With the mouse: click the picture for the channel list, double-click it for fullscreen, and use the wheel over the picture to change the volume (over the channel list it changes channels; to change channels over the picture too, see Settings → Mouse wheel; Ctrl/⌘ with the wheel always changes the volume). Moving the mouse shows the player controls. Besides play, ■ (stop: nothing plays or streams until you play again) and the speaker they have ⌕ (search), the guide, ⟲ (the channel before) and, at the live edge of a channel you can rewind, ◀10. On live TV, click the channel's name at the top for what is on, the ★ beside it to add it to your favorites or remove it, and the red ● after that to record the channel (see Recording). Typing aside, every key in the tables below has a way to do it on screen: a button (its tooltip names the key), a row, the A–Z rail, the mixer's rows, a click, double-click or the wheel on the picture, or the window's own close button.

On a Mac in fullscreen, switching to another desktop or app floats the picture in a small window on every desktop, as a browser does on a tab change; drag it anywhere, drag an edge or a corner to resize it (it keeps 16:9 and remembers its place and size), and double-click it (or come back to the player's desktop) to watch in fullscreen again. Settings → Float the picture when you leave a fullscreen desktop turns it off.

The channel list over the picture

Keys

These are also in the app under Help → Keyboard Shortcuts. Ctrl/⌘ means Ctrl on Windows and Linux and ⌘ (Command) on a Mac.

Watching TV

Keys What they do
↑ / ↓ Previous / next channel (volume during a movie)
0–9 Type a channel number
Backspace Previous channel
Enter Channel list
← / → Back / forward 10 seconds
Space Play / pause
X Stop: nothing plays or streams (Space plays it again)
L Go live
R Record the channel, or stop recording
G Guide
I Channel info
+ / - Volume up / down (the mixer)
M Mute
Tab The mixer's other row (while it shows)
J / K Sound 50 ms earlier / later (sync with the picture)
Shift+J / Shift+K Subtitles 50 ms earlier / later
A Picture: aspect ratio, deinterlacing, sleep timer; pressed again, the next ratio
Shift+I Statistics over the picture: show or hide
F / F11 / ⌃⌘F (Mac) Fullscreen
Ctrl/⌘+F Search
Ctrl/⌘+D Add or remove a favorite channel
P / Ctrl/⌘+P Picture-in-picture with the previous channel, or close it
S Swap the large and the small picture
V Multiview: several channels at once, or back to one
Alt/⌥+P Mini player
Esc Close what is open, leave the multiview or fullscreen; after a movie, back to the Library

Channel list

Keys What they do
↑ / ↓ Move
Page Up / Page Down Page
← / → Layer up / down
Enter Open or play
A–Z Find a genre or channel (every provider)
Backspace Delete a letter of the find
Ctrl/⌘+D Add or remove a favorite channel
Ctrl/⌘+P Open the channel in picture-in-picture
Delete (fn+⌫ on a Mac) Remove the channel from Recents
Ctrl/⌘+F Search
F11 / ⌃⌘F (Mac) Fullscreen
Esc End the find, then close

Guide

Keys What they do
↑ / ↓ Move between channels
← / → Earlier / later
Home Now
0–9 Jump to a channel number
Enter Watch the channel; a past programme from its start
R Record the programme at its time, or cancel its recording
Ctrl/⌘+F Search
F / F11 / ⌃⌘F (Mac) Fullscreen
G / Esc Close the guide

Movies and Series

Keys What they do
↑ / ↓ / ← / → Move
Enter Play or open
Home / End First / last title
A–Z Type to search every provider's movies, series and channels
Ctrl/⌘+F Search
/ Search, or type it in the search
Ctrl/⌘+D Add to or remove from My list
Delete (fn+⌫ on a Mac) Delete the recording (it asks first)
F11 / ⌃⌘F (Mac) Fullscreen
Esc Back; from the genres, back to live TV

Finding subtitles

Keys What they do
↑ / ↓ Move in a list; up from the top to the search field
Page Up / Page Down Page
← / → Between the languages and the subtitles
Enter Download and show the subtitles; in the field, search (or save the key)
A–Z Type what to search for (or the API key)
Ctrl/⌘+V Paste
Backspace Delete a letter
Esc Close

Anywhere

Keys What they do
Ctrl/⌘+1 Live TV
Ctrl/⌘+2 Movies
Ctrl/⌘+3 Series
Ctrl/⌘+4 Multiview
Ctrl/⌘+5 Recordings
Ctrl/⌘+O Open a file
Ctrl/⌘+, Settings
Ctrl/⌘+R Refresh channels and guide
Ctrl/⌘+Shift+R Refresh films and series
Ctrl/⌘+Q Quit

In the channel list, plain P types into the filter, so picture-in-picture there is Ctrl/⌘+P.

Sound and subtitles

On some channels the sound slowly drifts out of step with the picture. The ♫ button in the player controls opens the Sound panel: pick another sound track there when the channel or film has more than one, and use the Sync row to move the sound: − makes it play earlier and + later, 50 milliseconds at a time (up to 5 seconds either way). It reads, for example, "Sound 150 ms later", or "In sync"; Reset puts it back. J and K do the same from anywhere on the player. QiTV remembers the setting for each live channel, also after a restart, and uses it whenever that channel plays, big or small. For a film or an episode it lasts while that title plays.

The subtitles button beside it opens the Subtitles panel: Off, the subtitles the stream brings, and Load a file… to pick a subtitle file from your computer (.srt, .ass, .ssa, .vtt or .sub; it opens in the folder you used last). You can also drop a subtitle file onto the window while something plays. The file then shows in the list under its own name. While subtitles show, the panel has a Sync row too, for subtitles that come too early or too late; Shift+J and Shift+K do the same. A subtitle file and its timing last while that film, episode or channel plays.

Click anywhere else, or press Esc, to close a panel. While one is open, ↑ and ↓ move through it, Enter picks, and ← and → move the sync.

Subtitles from OpenSubtitles

For a film or an episode, the Subtitles panel also has Search OpenSubtitles…: QiTV looks for subtitles on OpenSubtitles.com, a free subtitle website: by the film's or series' TMDB or IMDb number when the provider lists one, else by the title that plays (with the film's year, or the series with its season and episode number; tags such as "EN:", "TR - " or "4K" in a provider's title are left out). Only subtitles made for that film or episode are listed. The languages that have subtitles are on the left with how many each has, your last language (or your computer's) first; the selected language's subtitles are on the right, the best first: from trusted uploaders and downloaded most. Machine translated ones are marked and come last; Hearing impaired ones are marked and come after the others, unless the last ones you picked were for the hearing impaired. Click one, or press Enter, and it downloads, shows at once and appears in the Subtitles panel under its own name. If the title is not found (a title translated by the provider often is not), type its original or English title in the search field at the top and press Search. When OpenSubtitles finds subtitles only for other titles, it lists them all the same, each with the title it was made for: check it before you pick one. The next time that film or episode plays, the Subtitles panel offers the same file again at its top ("… (OpenSubtitles)"), without a new download.

OpenSubtitles needs an API key. The release downloads of QiTV may come with one. If yours does not, the first search asks for one: Get a free key opens the OpenSubtitles website, where you make a free account and then create a key on its "API consumers" page; copy the key, click Paste (or press Ctrl/⌘+V) and Save. You can change it later in Settings → Subtitles.

Without signing in, OpenSubtitles allows 5 downloads a day per internet connection. To get more, enter your OpenSubtitles username and password in Settings → Subtitles (optional; Sign out there removes them). After each download QiTV says how many downloads you have left today and when more come back. Downloaded subtitles are kept in the subtitles folder beside QiTV's settings (see Portable mode for where that is).

Picture, sleep timer and statistics

The picture button beside the subtitles button (or A) opens the Picture panel. Click ‹ or › on a row (or use ← and →) to change it:

  • Aspect ratio: Auto (the channel's own shape), 16:9, 4:3, or Fill the window, which crops the picture to the window's shape so there are no black bars. QiTV remembers it for each live channel, also after a restart. Pressing A again while the panel is open moves to the next ratio.
  • Deinterlacing, for TV channels whose picture shows fine horizontal lines on movement: Auto (VLC deinterlaces pictures marked as interlaced), On or Off, for every channel. After switching it on or off, Auto comes back the next time QiTV starts.
  • Sleep timer: 15, 30, 60 or 90 minutes, or End of the programme when the guide knows when the programme ends. The row shows the time left. A minute before the end QiTV says playback stops soon; click Keep watching (or press Enter) to turn the timer off. Otherwise playback stops, fullscreen ends, and your computer may go to sleep again. The timer is not kept after QiTV closes.
  • Statistics (or Shift+I) shows technical details over the picture: the video and audio format, the picture size and frame rate, pictures shown and dropped, the bitrate, hardware or software decoding, whether the channel plays through time-shift, and how far behind live it is.

In picture-in-picture the panel changes the big picture; in the multiview, the selected tile.

Pause and rewind live TV (time-shift)

QiTV keeps the last few minutes of every live channel you watch, so you can pause, rewind and catch up like with a TV recorder. Press Space to pause and again to go on from where you paused; ← and → jump 10 seconds; L (or Go live) goes back to live. The bar shows how far behind live you are. While you are behind, − and + beside the speed play slower or faster (0.5× to 2×), say faster to catch up; click the speed for normal again. Movies and episodes have the same control.

Time-shift: paused and playing on behind live

  • In memory, by default. Each stream has its own memory for this, set in Settings → Time-shift → Memory per stream: 128, 256 (the default) or 512 MiB, about 2, 4 or 9 minutes of HD video.
  • On disk, only if you allow it. Tick Use disk for a longer time-shift buffer in the same tab and choose the size with the slider, from 256 MiB to 16 GiB (2 GiB is about 36 minutes of HD). The size is the total for every channel's buffer on disk; the small picture of picture-in-picture keeps its buffer in memory, unless its channel's buffer was already kept on disk. This is temporary history, not a recording: when the space is used up, the oldest part goes first.
  • Leaving a channel keeps its buffer. A zap, another channel, a film or quitting QiTV keeps what the buffer holds. Come back to the channel by any route and it plays live; if you had paused or rewound, Left off at 20:10 · Resume shows at the top for a minute (on the phone too): click it, or press Enter, to go on from there. Nothing records a channel you left (providers allow few streams), so the bar shows the time away as a gap, which playback and seeks skip.
  • For a day, and after a restart. On disk, kept buffers last 24 hours and are still there after quitting QiTV; when the space is used up, the oldest parts of the channels you left go first. In memory, only the channel you left last keeps its buffer, until QiTV quits. Turning the disk buffer off removes what it kept.
  • When the channel can't open. If a channel you come back to doesn't open (say the provider still counts your last connection), its kept buffer plays all the same; Go live tries the channel again.
  • As far back as the channel's server keeps it. Some live channels' own servers keep hours of the channel, a day for some. On such a channel the bar reaches as far back as the server keeps it (the part before the buffer is dashed), and ←, the bar and ⏮ go back there; so does the guide's ▶ Watch from the start, on the channel you watch or one you watched earlier. What the buffer holds always plays from the buffer: only what lies before it comes from the server, a minute ahead of what plays, and at the buffer's start playback goes on into the buffer without a break; what came from the server plays again at once until you go live, leave the channel or go back further. With a provider that limits its streams, the live stream pauses meanwhile (the bar shows a gap there) and opens again when you are back in the buffer or go live; while such a channel records, QiTV can't go past the buffer, and before the buffer it can't start a recording (it says so).

Catch-up: your provider's archive

Many providers keep the last days of some channels, so you can watch what was on earlier. QiTV knows which channels have such an archive from your provider's channel list (Xtream providers, M3U playlists that say so, and STB portals that mark their archived channels), and uses it where its own time-shift buffer ends:

  • Rewind further back. On a channel with an archive, the time-shift bar reaches half an hour further back than the buffer; that part of the line is dashed. Drag there, press ← at the start of the buffer, or press ⏮ for a programme that began before it, and QiTV plays the provider's archive from that moment ("From the provider's archive"). L or Go live goes back to the live channel.
  • Through the buffer, when it can. Most archives come as a stream QiTV can buffer. Then the archive plays as part of the channel's own bar (so does the guide's Watch from the start on the channel you are watching): the bubble over the knob says which moment plays (with the day, if it is not today), what came of the archive replays at once, and when the archive reaches the buffer's start, playback goes on into the buffer instead of fetching that again. Other archives, an STB portal's recordings and Watch from the start on another channel play the archive on a bar of its own, from that time to now, and ←, →, ⏮ and the bar move within it.
  • Watch a past programme from the start. In the guide, ← (or ‹) also goes back in time on such channels. The programme at the left edge of the guide, or a past one you click, is outlined: press Enter, double-click it, or click ▶ Watch from the start at the bottom of the guide. That button also plays the programme on now from its beginning.
  • One stream at a time. The archive is another stream from your provider, so with a provider that limits its streams QiTV pauses (or closes) the live stream before it opens the archive, and the other way round when you go back to live: the archive never takes a stream of its own.
  • Some archives don't answer. A channel can claim an archive the provider doesn't have. Then QiTV says so and keeps playing (or goes back to live). When the provider says it has nothing twice, for two different times, QiTV doesn't ask for that channel's archive again for three days.

How far back you can go depends on the provider (often one to seven days). An STB portal's archive plays programme by programme: QiTV asks the portal for the recording of the guide's programme at that moment and moves on to the next programme's at its end, so it needs the guide from the portal itself (Settings → EPG), and the guide offers only programmes the portal lists as recorded. Portals differ in what they keep and how they answer, so some marked channels may still not play; QiTV then says so and stays live. Archive times follow your provider's time zone, which QiTV reads from Xtream providers when it loads their channels (refresh the channel list once after updating); an M3U playlist's Xtream-style channels use the time zone of your Xtream provider on the same server, else UTC. While the archive plays on a bar of its own, R doesn't record: recordings come from the live buffer.

Recording

Press R, or the red ● after the channel's name and ★ at the top of the player controls, to record the live channel you are watching; press it again to stop. While it records, the ● is lit and ● REC 01:23 beside it counts the time.

  • From where you are watching. If you have paused or rewound, the recording starts there, with what the time-shift buffer holds after it, and then goes on with the live stream.
  • It keeps recording. The recording keeps the channel's stream for itself and records on through pauses, rewinds, other channels, films and the Library; several channels can record at once, as far as your provider's streams go. While you watch something else, ● REC with the channel and its time shows at the top right of the picture with the player controls, and for a few seconds by itself when a recording starts or ends (in the Library it stays at the bottom left): click it to go back to the channel, to stop the recording, or for Manage Recordings…. Back on the channel, it plays live, and you can rewind to the start of the recording while it still records. Picture-in-picture of that channel shows the recording itself, with no new stream.
  • A stream for what you watch meanwhile. Another channel, film or episode from the same provider needs another stream. When the provider has none left, QiTV asks whether to stop the recording: Keep recording (chosen first, and on the TV what happens when no one answers within a minute) stays where you are; Stop recording saves it and goes on. Play in VLC or MPV and the phone's Watch ask the same; the phone's question shows on the phone. A provider that allows one stream without saying so and drops the older one when another opens: QiTV stops the newer stream instead and says so, so the recording goes on.
  • Until you stop it. It stops when you press R or the ● again, from the ● REC sign, after 24 hours, or when less than 2 GB is left on the disk. Quitting QiTV while it records asks first. A message then says Recording saved with the file's name (and why it stopped, if you did not stop it). ■ (stop) leaves recordings going.
  • In your Movies folder, and on the Recordings tab. Recordings go to QiTV in your Movies folder (macOS) or Videos folder (Windows and Linux). Settings → Time-shift → Recordings changes the folder and opens it (so does File → Open Recordings Folder). The Library's Recordings tab shows them as tiles, newest first, each named after its programme with its channel, length and NEW until you play it; a tile plays it, from where you stopped (see Managing recordings). The phone remote's Library lists them under Recordings, and watching on the phone a recording plays there, from where you stopped: at home, QiTV hands the file to the phone itself, nothing re-encoded (a channel in HEVC or with only MPEG sound plays on the TV only); one still recording plays as far as it got.
  • As the channel sends it. Each file is named after the channel and the time, for example My Channel 2026-10-19 21.30.ts: an MPEG-TS file with the channel's own picture and sound, not re-encoded, which VLC, MPV and most players play.
  • No new stream to start. A recording is written from the time-shift buffer of the stream that plays, so starting one never asks your provider for another stream. That is also why a channel that plays without time-shift can't be recorded: its button is dimmed and says so.
  • In the multiview the button records the focused tile. A recording goes on when the focus moves, or when its channel becomes the small picture of picture-in-picture: that tile or small picture says REC on its label. Changing or closing a tile that records asks first; leaving the multiview keeps its recordings going.

Live latency

Live streams arrive a little behind the broadcast. Settings → Live latency chooses how far behind QiTV plays:

  • Auto (recommended, and the default) learns it for each channel from how the channel's pieces arrive: about 2.5–3.5 seconds for a steady stream, more for one that arrives in uneven pieces or in bursts (never less than one burst). It plays a channel further behind only after the picture ran dry, not for a pause the buffer covered, and quiet minutes bring it closer again. QiTV remembers what it learned per channel for the next time. At the live edge the player controls show how far behind the channel plays, with "adjusted" while trouble holds it further back, for example "Stay live ● ≈ 7 s behind · adjusted" (in a small window "adjusted", then "Stay live", give way first).
  • Low (about 1 second, starts sooner), Normal (about 2.5 seconds) or Stable (about 6 seconds, for unreliable streams) keep the same distance on every channel. When you update, QiTV moves you to Auto once, whatever you had chosen before; a latency you choose in Settings afterwards stays.

QiTV gently speeds playback up or down to stay there, only when the distance has drifted for a while: a few percent, eased in and out, at most about once every 5 minutes (the dot beside the distance is amber meanwhile). When a channel has fallen far behind (more than about 8 seconds), QiTV jumps closer once instead, at most once a minute, starting where the picture is complete. A channel starts at that distance too, not at the oldest part of what the provider sends; when a provider sends a backlog right after the start, QiTV picks the start again within seconds. On a channel where that does not play smoothly, QiTV notices within a few seconds, plays it at normal speed only and remembers that for a day; then it tries again. Channels that cannot be time-shifted play directly; under Auto they play as with Normal. A few channels whose streams can't be time-shifted smoothly play without rewind too; QiTV notices this by itself and tries again a day later.

Picture-in-picture

Watch a second channel in a small picture in the bottom-right corner:

  • P (or the player controls' second-channel button) opens the channel you watched before, small; press P again to close it;
  • in the channel list, right-click a channel and choose Open in picture-in-picture, or highlight it and press Ctrl/⌘+P; the channel can come from any of your providers;
  • click the small picture or its ⇄, or press S, to swap the two: the small one becomes big;
  • the sound follows the big picture. The speaker on the small picture turns its sound on or off. + and - (or the speaker in the player controls, beside ♫) show the mixer, which sets each picture's volume (Tab moves to the other row) and hides after a few seconds; without picture-in-picture it shows only the main volume;
  • the × on the small picture closes it.

Picture-in-picture is for live TV, and it needs two streams: a provider that allows two at a time, or one stream each from two providers. A film or an episode from the Library is the one exception: it takes the big picture and keeps the channel you were watching small (see Keep watching while you browse).

Picture-in-picture with the volume mixer

Multiview

Watch several live channels side by side: press V, choose View → Multiview (Ctrl/⌘+4) or click the grid button on the player controls. The channel you are watching becomes the first tile and an open picture-in-picture the second; the others show +.

  • Click a tile to give it the focus: its sound plays, and the player controls, the channel list, zapping and the banner act on it. Click + to choose a channel for that tile, or drag a channel from the channel list onto any tile.
  • Point at a tile for its own controls, which act on that tile without moving the focus: pause or play, its speaker, LIVE or how far behind live it plays (click to go live), the big picture (back to one picture with this tile big) and ✕, which closes the tile and gives its stream back to your provider. Small tiles keep the speaker and ✕.
  • The layout chip beside the grid button (the grid's picture, 2×2 and ⌄) shows the layouts to pick from: 1×2, 2×2, 3×2 and 3×3. 3×2 and 3×3 need hardware decoding (Settings, after a restart); without it they are dimmed.
  • The sound follows the focused tile until you mix it: change the level or the speaker of a tile without the focus (in the mixer, or on the tile) and your mix stays as you move the focus. The mixer says which it is; Follow focus there goes back. Leaving the grid ends the mix: the big picture is heard.
  • The grid you leave is kept: next time, the Last grid chip (or View → Restore Last Multiview) brings its channels back.
  • Each tile asks your provider for a stream of its own. When a provider has no stream to spare, the tile says so and keeps the channel: click it to try again. QiTV never retries by itself.
  • V, Esc, a double-click on a tile or the grid button (one picture, while the grid shows) goes back to one picture: the focused tile becomes the big picture and the tile you had before it stays as picture-in-picture. Picture-in-picture itself waits until you leave the grid.

Each tile's label shows LIVE, or how far behind live it plays (−00:42). Tiles without the focus play at normal speed and only jump back to live when they fall far behind (never while paused); each can be paused from its own controls, and rewound like the big picture once it has the focus. Its time-shift buffer is in memory: the focused tile gets the memory per stream (Settings), the others a short one of 64 MiB ("multiview_tile_ram_mib" in config.json changes it; at least 48, enough for a 4K channel). A tile you paused or rewound keeps what it plays until it is back at live.

Casting to a TV

QiTV can send what plays to a Chromecast, or a TV with Chromecast built in, on your network. The cast button in the player controls (it shows when QiTV can cast) opens a menu of the devices found; QiTV starts looking the first time you open it. Pick one: the channel goes on from where it was in its time-shift buffer, a film from where it is, and a Playing on … pill says where the picture went. Stop casting (in the menu, or on the pill) brings it back.

  • One picture goes to the device: casting leaves the multiview and closes picture-in-picture.
  • The cast stays on for whatever you play next, until you stop it or the device goes away (QiTV then says so and plays here again).
  • Your computer streams to the device and converts the picture or the sound when the device can't play them as they are, so keep QiTV open while you cast.
  • The phone remote's More → Cast to a TV does the same.

Phone remote

Use your phone as the remote, in its browser: no app to install. Choose QiTV → Phone Remote… (it turns the remote on the first time): a code shows on the TV. Scan it with the phone's camera; the browser opens the remote, and the phone is paired from then on (the remote's menu, ⋯, has Add to Home Screen to keep it one tap away).

  • The arrows, OK and Back work as the keyboard's, wherever you are (the channel list, the Library, the guide); a held button repeats like a held key and stops where you let go. TV, Movies and Series jump to those pages; the volume and channel rockers, ⏪ ⏯ ⏩, Mute, ● (Record) and LIVE (back to live; lit while you are behind) sit below. More holds the channel numbers, Picture in picture, Swap, Multiview, Picture, Subtitles and Sound (the player's two panels: the subtitle and sound tracks, and AI captions with their language and the language they are translated into), Full screen, Cast to a TV and Stop. While a channel records in the background, a ● REC line names it, with Go back and Stop recording; when something you start from the phone needs the stream a recording holds, the phone asks whether to stop it. The phone's menu (⋯) switches the arrows for a touchpad: flick for a step, drag and hold to keep moving, tap for OK.
  • The phone also shows what's on, a Guide and the Library. The Guide opens where the TV's channel list is, on the channel playing; ‹ Groups goes up to the groups (Favorites, Recent and the provider's own). A channel opens its card: its timetable and Watch (a past programme plays from the start when the provider keeps an archive); the ▶ at the end of its row tunes at once. A programme on now or still to come has ● Record and Series under it, and ● Cancel recording once it is scheduled (see Scheduled recordings). The Library lists Movies' and Series' genres, Continue first, then a genre's titles as the Library's cards; its find box finds genres and, below them, the section's films or series, as QiTV's search does. Recordings opens on one page, as the Library's Recordings tab on the TV: what records now (Watch on the TV, Stop), the next airings (tap one for what it allows: Try now, Skip, Cancel Recording…; when there are more, Coming up › lists them all), the latest recordings, and All recordings › for each channel's, which play on the phone. The switch at the top of the Guide and the Library says where a tap plays: off on the TV, on (Phone) on the phone; ☰ at the top of the Remote shows the channel list in place of the arrows, with the same switch. Every find box searches the whole list shown, and browsing on the phone leaves the TV where it is until you tap. Search types on the phone and shows the TV's results on both.
  • At home the phone talks to QiTV directly over your Wi-Fi. With Reach QiTV from any network on (Settings → Phone remote), it also works on mobile data or another network, through the QiTV relay; the relay passes along scrambled messages it can't read (Noise, end to end), and sees only that a phone and a QiTV talk, how much, and from which addresses. When the phone is on the TV's network it switches to the direct connection by itself.
  • The code on the TV changes every minute, pairs one phone, and only works while it shows. Settings → Phone remote lists the paired phones; Remove cuts one off at once. A phone can pair with several QiTVs and choose between them.
  • The first time the remote is turned on, the system may ask whether QiTV may accept incoming connections (Windows always, macOS when its firewall is on): allow it for your home network. QiTV answers only addresses of a home network.
  • What it doesn't protect against: someone who can change the traffic on your home network, and a phone that is stolen unlocked (remove it in Settings).

The guide

Press G (or the guide button in the player controls) for the programme guide (EPG): the channels of the group you are watching, from the current half hour on, up to 24 hours ahead. Move with the arrow keys, type a number to jump to a channel, and press Enter to watch it. With the mouse, click a channel and double-click it to watch; ‹ and › beside the day move in time, and ⌕, ⛶ (fullscreen) and × (close) are at the top right. The bottom shows the highlighted programme's description. On channels whose provider keeps an archive, the guide also goes back in time and plays past programmes from their start (see Catch-up).

The programme guide

The guide comes from your provider (STB and Xtream), or from a guide file or web address of your own (XMLTV): choose it in Settings → EPG. If a provider's guide is off by whole hours (programmes start an hour before or after the guide says), set its Guide time offset in Settings → Providers (−12 to +12 hours, in half hours): the guide, the banner, what is on now and next, and the marks on the time-shift bar all move together.

Scheduled recordings

Record a programme while you are away: in the guide, pick a programme on now or still to come and choose Record at the bottom (or press R), or Record series for every airing of that title on that channel, as the guide lists them. A scheduled programme has a red dot in the guide; Cancel recording (or R again) takes it off. The phone remote's timetable does the same.

Record at a time needs no guide: right-click a channel, use the button at the bottom of the guide, or + At a time… on the Library's Recordings tab, and choose the time it records (From, To: an end before the start is the next day's), once on a day, every day, Monday to Friday, or on the days you tick, with a name if you like. One that repeats records on each of its days until you cancel it on the Recordings tab, where Edit… changes it. The phone remote's timetable has Record at a time too, also for a channel without a guide. Times are the computer's clock's.

  • QiTV records it at its time, from a minute before it starts to three minutes after it ends, in the background: nothing opens on screen, and you can watch something else meanwhile. A message says when one starts. The file goes to your recordings folder like any recording, and the Recordings tab names it after the programme.
  • QiTV has to be open. It keeps the computer from going to sleep by itself while it runs, but a closed lid or a computer put to sleep misses recordings. One whose time passed while QiTV was closed is said the next time QiTV starts.
  • What you watch records on its own stream. When the programme's channel is playing at its time (in the big picture, picture-in-picture, the multiview or a recording player in the background), QiTV records it from that player's buffer, from the programme's start as far back as the buffer goes: no second stream, so an account that allows one stream records the channel you watch. The player shows ● REC as if you had pressed R; change the channel and it records on in the background, and it stops at the programme's end.
  • It needs a stream of its own. A scheduled recording asks your provider for a stream at its time. When the provider has none to spare (because another channel is playing on an account that allows one stream, for example), QiTV tries again every minute while the programme airs and never stops what you are watching for it; it says the recording was missed only once the programme is over. The next programme on a channel that records needs no other stream: half a minute into it the first file ends, and the next one starts a minute before its programme.
  • Watching it takes no second stream. Tune the channel while it records (from the channel list, P for picture-in-picture, Go back to on the ● REC sign or Watch on the Recordings page) and it plays from the recording's own stream and buffer: your provider sees one connection, nothing asks you to stop the recording, and you can pause and rewind within its buffer (a few minutes, in memory). The small picture says REC; R there says it already records on schedule. When the recording ends while you watch, the stream stays open for you until you change the channel (and the next programme scheduled on that channel records on it).
  • Kept when it is cut short. When the stream or the time-shift helper stops a recording, its file is kept and the rest of the programme goes into another file.
  • One file for overlapping ones. A recording that falls within another on the same channel (a programme during your evening's Record at a time, or one scheduled twice) goes into that one's file.
  • On the REC sign. While one records, ● REC with its channel shows at the top right of the picture with the player controls: Stop recording there stops it for this airing (a series records its next airing), Go back to plays its channel.
  • The Recordings tab lists what is to come: Cancel Recording takes one off, Skip passes over one airing of a series, Edit… changes one that is not a series.

Managing recordings

Everything about recording is on one tab: the Library's Recordings, after Movies and Series. Open it with Ctrl/⌘+5 (View → Recordings), the Recordings row at the bottom of the channel list's sources, or Manage Recordings… on the ● REC sign. The tab has a red dot while something records and an amber one when a recording needs your attention. Like Movies, it has rows on the left and what the row holds on the right, as tiles: a recording's tile shows a picture from it (taken once from the file, quietly, in the background), a scheduled one its channel's logo, each with its title, channel and time. The strip under the chosen tile has its buttons; Return or a right-click lists them too.

  • Tonight, where the tab opens: the recorder's home. At the top, Recording now with how long each recording has run, how far it got and when it ends (▶ Watch plays its channel, ■ Stop stops it and keeps the file); Next, the next recording and how soon it starts (Edit… changes it, unless it is a series); and Add a recording: + At a time… records a channel by the clock (see Scheduled recordings), and each provider's line says how many of its streams are in use. Below them, the guide: your favorite channels from half an hour ago to three and a half hours ahead, a line at now. The day buttons go up to three days ahead, as far as the guide's list reaches (Settings → EPG → EPG List Window; 0 lists all of it), ‹ and › move half an hour, and the button at the right (★ Favorites) picks the channels: Recent, all channels or one of your provider's groups, and, with two providers or more, each provider's channels. Click a programme on now or still to come for ● Record or ↻ Every airing (one on now also has ▶ Watch); a programme that records is red and a scheduled one is marked, and clicking it offers Cancel, or for a series Skip (this airing only) and Cancel series. At the bottom, Recently recorded, with All recordings ›.
  • Coming up. What records now or waits for a stream, then every scheduled airing by day (Today, Tomorrow, …), each tile with its time and whether it records Once, Repeats or is a Series. A due recording with no free stream says why; Try now tries at once instead of in a minute, and Skip gives up on this airing (a series records its next one). Edit… changes a one-time recording's or a timer's day, times, days of the week or name (a one-time recording can become one that repeats, and back); Cancel Recording takes it off. QiTV looks a week ahead (for a series, as far as the guide goes) and warns when recordings would need more of a provider's streams at once than it allows, so you can fix it before one is missed. Two on the same channel back to back, or one within another, share a stream and never clash.
  • Series & timers. What repeats: a programme's every airing, and a channel recorded at a time on its days, each with when it records next; Edit… changes a timer, Remove stops either.
  • Needs attention. Recordings that were missed or failed, with why and what helps: QiTV was closed, the computer was asleep, no stream was free (stop what else plays then, or raise Max simultaneous streams in Settings → Providers if your plan allows more), or what the channel or the provider did. Play plays what was recorded before a failure; Dismiss (or Dismiss all) takes them off the list.
  • Recorded. All and a row for each channel, the channel with the most recordings first, show the recordings newest first, each with its length and NEW until you play it. A tile's strip plays it (Resume or Start over once you played part of it), Show in Folder and Delete… (Delete too; it asks first, and a file still being written can't be deleted).
  • Folders & streams. The folders recordings are listed from, with how many recordings each holds, their size and the disk's free space; the folder new recordings go to comes first and warns when its disk is almost full. Add a place… lists the recordings of another folder (an external drive, an older recordings folder), Use for new recordings makes a place where new ones go (the old one stays listed), Remove from list stops listing a place (its files stay on the disk). Above them, a card for each provider with a stream in use or a recording scheduled shows how many of its streams are in use out of the number it allows, and what holds each: the channel you are watching, picture-in-picture, a multiview tile, a recording (in red).

Typing in the find box above the rows (↑ from Tonight goes into it) finds recordings by title or channel, and, under In the guide, the programmes still to come whose title holds the words, first on the guide's channels, then the provider's, then every provider's (those whose guide QiTV has loaded): ● Record or ↻ Every airing schedules one. With the keys: ↑ and ↓ move along the rows, → goes into the row's page and ← back; on Tonight, ↑ and ↓ move from the cards through the guide's channels to the recent recordings (↑ from the first channel reaches the days, ‹ › and the channels' button; PgUp and PgDn move a screen of channels), Return opens a programme and presses its button (← and → choose it), Esc closes a programme, then goes back to the rows and to live TV.

The Library: movies and series

Ctrl/⌘+2 opens Movies and Ctrl/⌘+3 Series (also from the channel list's sections). What you were watching keeps playing in a corner (see below); with nothing playing, Live TV (or Ctrl/⌘+1) takes you back to the last channel. While a movie or an episode from the Library plays, ‹ Library in the player controls (or Esc) takes you back to where you were in the Library. The ⛶ at the right end of its top bar switches fullscreen.

  • Genres are on the left. Above them: Continue (what you started watching), New (the most recently added titles, when your provider says when it added them) and My list (titles you saved with ★ or Ctrl/⌘+D).
  • Posters fill the rest. The highlighted one opens a strip with its year, running time, genre, rating, story and cast, and Resume, Start over and ★.
  • Details from TMDB. Where your provider gives a film or a series no poster (or one that doesn't load), story, year, running time, genre, rating or cast, the Library shows those of TMDB, in QiTV's language. QiTV finds the title by the TMDB or IMDb number your provider lists, else by its name and year; when it can't be sure it is the same film, it shows nothing rather than another one's. It sends TMDB only the title and its year, never for a title whose name or group looks adult or that parental controls hide, and keeps the answers (and TMDB's posters) for a month. Turn it off in Settings → Film and series details from TMDB; a build from the source code needs your own TMDB API Read Access Token there.
  • Sort by recently added, A–Z, year or rating. In a long genre, type a letter (or use the A–Z letters on the right edge) to jump there.
  • Providers: the button with your provider's name at the top right ticks whose films and series the Library shows: one provider, several mixed (the button then names them), or, with two or more providers, All providers: each provider's genres under its name, and Continue, New and My list mixing the providers shown (the strip then names a title's provider). The menu stays open while you tick, and what you ticked shows when it closes. All providers ticks every provider; with every one ticked it clears them all, so you can tick just the one you want. This only changes what the Library shows, not the channel list or what plays.
  • Search (Ctrl/⌘+F or /) finds channels, movies and series in the lists QiTV has loaded from all your providers. A hit plays from its own provider, without switching provider first.

The Library: a genre's posters and a film's details, with the channel playing on in the corner

QiTV keeps each provider's film and series lists and loads them again after six hours. For an Xtream provider and a Jellyfin or Emby server this happens in the background: a list QiTV has kept shows at once and the new one takes its place where you are, and a few seconds after such a provider is ready its lists load ahead, so the Library opens without waiting. ↻ in the channel list's top row (Ctrl/⌘+R) loads the provider's lists again now.

A series opens on its seasons and episodes. Episodes you finished have a ✓, and started ones a progress bar with Start over. When an episode ends, the next one starts after a 10-second countdown, also across seasons (Settings → Auto-play).

A series with its seasons and episodes

Keep watching while you browse

Opening the Library or the search (⌕, Ctrl/⌘+F) doesn't stop what plays. The TV shrinks into a corner of the Library, a third of the window wide, with picture-in-picture inside it when it is open, and goes on playing with its sound:

  • its buttons are at its top right: the speaker mutes it or turns the sound back on, ⤢ gives it the whole window back, and × stops it (the Library stays);
  • drag it to another corner if it is in the way; QiTV remembers the corner;
  • a click on it, ⤢, Live TV (Ctrl/⌘+1) or Esc from the genres brings the TV back exactly as it was: nothing restarts, and rewound live TV is still where you left it;
  • a film or an episode you play takes the big picture and keeps the channel you were watching in the small one (a small picture that was already open closes: QiTV has two players). If the film's provider has no stream to spare, QiTV closes the small picture from that provider and tells you;
  • a channel you pick in the search plays in the big picture; the small one stays.

Jellyfin and Emby

Add your Jellyfin or Emby server as a provider (see Adding a provider), and its films and series join the Library, next to your other providers' and searched with them. Older Jellyfin servers and Emby work too.

  • Its libraries are the genres: All first, then Continue watching (what you started, here or in the server's own apps) and each of the server's libraries by its name, with the server's posters, years, ratings and stories. A series opens on its seasons and episodes as any other.
  • The file plays as it is. QiTV plays a title's file straight from the server, without the server converting it, so the server's processor stays free. The ⚙ in the player controls lists the title's versions (each plays as its file is) and, for a slow connection, the server's conversions below the version playing (1080p · 8 Mbit/s, 720p · 4 Mbit/s, 480p · 2 Mbit/s); the title goes on from where it is. The first conversion on a server asks first, since it uses that server's processor; a conversion goes on for that server's titles until QiTV closes, and choosing a version as it is ends it.
  • 4K on a 4K screen. When a title has a 4K version and another one, QiTV plays the 4K one on a 4K screen and the other below it. A title that only exists in 4K plays anywhere: it still comes as it is, and your computer scales it down. Settings → 4K versions (Jellyfin, Emby) changes that: Always plays the 4K version on any screen (sharper when scaled down, but more data), Never none.
  • The server keeps up. Where you stop is told to the server, so its own Continue watching and watched marks follow, and a title you started only in the server's apps starts here where you left it there.
  • Your password isn't kept. QiTV keeps the sign-in the server gave it when you pressed Verify Provider, and the server lists QiTV among its devices. If the server ends that sign-in, QiTV asks you to verify again.
  • The phone remote's Watch on this phone plays a server's titles from the server itself, at home. A server's live TV, and exporting a server to M3U, are not part of QiTV.

Favorites

Press Ctrl/⌘+D on a channel, right-click it in the channel list, or click the ★ beside its name in the player controls, to add it to or remove it from ★ Favorites at the top of the channel list. In the Library, Ctrl/⌘+D and ★ do the same for My list.

A star belongs to one provider and is kept by name: starring a channel called "News" at one provider doesn't star a "News" at another, while within one provider two items with the same name share one star. A provider's ★ Favorites and My list show its own stars; All providers shows every provider's, each with its provider's name. Stars from QiTV 2.0 and earlier stay on every provider that has something of that name; un-star one at one provider and the others keep theirs.

Parental controls

Settings → Parental controls sets a PIN (4 digits or more). With a PIN set:

  • Hide what you choose. Right-click a group or a channel in the channel list and choose Hide (parental controls). Hide groups whose names look adult (in the same Settings tab) hides every group, live or in the Library, whose name says it is for adults (XXX, Adult, 18+ and the like), also the ones your provider adds later.
  • Locked, they are gone everywhere: the channel list, the guide, changing channels, the Library, the search and the phone remote, with the recordings of a hidden channel. QiTV is locked unless you unlock it: Unlock for an hour… asks for the PIN, Lock now locks again. When QiTV locks (also when the hour runs out), a hidden channel that plays stops.
  • Never in the history. What you hid leaves Recent, Continue and the channel QiTV starts on, also what was watched before you hid it, and stays out of them while unlocked too.
  • Only with the PIN. The list of what is hidden shows once you unlock with the PIN; Show again brings one back, and unticking the adult names needs the PIN too. Changing or removing the PIN asks for the current one. QiTV keeps only a salted hash of the PIN, never the PIN itself.

Exporting to M3U

File → Export saves channels, movies or episodes as an M3U playlist for VLC or other players:

  • Cached Content… saves what QiTV has loaded of the section you are in (live TV, movies or series);
  • All Live Channels… saves every live channel of the provider;
  • Complete Series (Fetch All)… (STB providers, in Series) first loads every season and episode. A message shows how far it is; Esc cancels it.

The exported files contain the stream addresses, which VLC and most players can open directly.

Playing in another player

Any channel, movie or episode can go to VLC or MPV (when they are installed):

  • right-click a channel in the channel list, or a film's poster or an episode in the Library: Play in VLC and Play in MPV open it in those players, and Copy stream link copies its address;
  • while it plays, the Open in external player button on the right of the player controls (a box with an arrow) offers Play in VLC and Play in MPV.

QiTV closes its own stream first, so a provider that allows one stream still works.

To open every channel in one of them instead of on the TV screen, turn on Always play in VLC or Always play in MPV in Settings.

Portable mode

By default, QiTV stores its settings and cache files in your user folder:

  • Windows: %APPDATA%\qitv
  • macOS: ~/Library/Application Support/qitv
  • Linux: ~/.config/qitv

To enable portable mode (useful for USB drives or keeping everything in one folder), create an empty file named portable.txt in the same folder as the QiTV program (or beside main.py when running from source). QiTV then keeps all its settings and cache files in that folder instead.

Running from source

Build and run QiTV from the source code

Running from source needs Python 3.14 and VLC installed on your computer (from videolan.org, or your Linux distribution's vlc package): unlike the release downloads, the source code does not include VLC. Python 3.15 is not yet supported by the Qt and theme libraries.

git clone https://github.com/ozankaraali/QiTV/
cd QiTV
python3.14 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python main.py

Or with uv: uv sync --frozen --dev, then uv run python main.py. The tests run with uv run python -m unittest discover -s tests.

To try QiTV without a provider, uv run python scripts/make_demo_content.py --out build/demo --serve serves the demo content on your computer and prints how to start QiTV with it. --screenshots docs/screenshots instead of --serve takes this page's screenshots again.

A build from the source code has no OpenSubtitles API key of its own: enter yours in Settings → Subtitles (free, see Subtitles from OpenSubtitles). The release builds get theirs from CI: before packaging, each build runs scripts/write_build_keys.py, which writes the repository secret named QITV_OPENSUBTITLES_KEY into services/_build_keys.py (without that secret, as in a fork, the key stays empty). The file in the repository stays empty: never commit a key into it.

Debug switches

Environment variables for troubleshooting

QiTV keeps its log in a file too, a few runs' worth: ~/Library/Logs/QiTV/qitv.log on a Mac, %LOCALAPPDATA%\QiTV\Logs\qitv.log on Windows, ~/.local/state/qitv/qitv.log on Linux. Addresses and query strings are left out of it; it says how QiTV ended each time, and after a crash a crash.log beside it holds where each thread was. Attach them when you report a problem: Help → Show the Log File… opens their folder. For a problem that is hard to pin down, tick Settings → Detailed log (for troubleshooting): the log then also gets every step QiTV takes (still without addresses or passwords), and every message QiTV showed is in it either way. What a switch below logs lands in that file too.

Set these before starting QiTV (for example QITV_DEBUG_QT=1 python main.py):

  • QITV_VLC_LOG=/path/to/vlc.log writes VLC's detailed log to that file. This log is not cleaned up: it contains the addresses of the streams you play, which often include your provider username and password. Never share it publicly.
  • QITV_DEBUG_QT=1 prints Qt's warnings about timers and threads to the terminal.
  • QITV_DEBUG_CURL=1 logs the guide requests QiTV sends to an STB portal as curl commands you can run yourself, with the cookies (your MAC address, serial number and device ID) and the session token masked. QITV_DEBUG_CURL=raw logs them unmasked: never share that output.
  • QITV_CAPTURE_DIR=/path/to/folder saves what time-shift receives from the provider each time a channel opens, so a glitch can be replayed later: <date-time>-<id>.ts holds the stream's bytes as they arrived, and <date-time>-<id>.times has one <cumulative bytes> <seconds> line per read (lines starting with # are comments, such as # reconnect <seconds>). An HLS channel whose sound comes as a separate stream also gets <date-time>-<id>.audio.ts and .audio.times with that sound's pieces: scripts/replay_capture.py weaves them back in, and a player plays the pair with sound (for example mpv <name>.ts --audio-file=<name>.audio.ts). It stops at 2 GiB or 3 hours per channel and never leaves less than 1 GiB free. The files are written by the thread that reads the stream, so point this at a local disk. The files hold the provider's stream: keep them private (QiTV makes them readable by you only). They never contain the stream's address or your credentials.

Disclaimer

This application bundles a list of publicly available IPTV channels from around the world. The channels are not hosted by this application or respective repository. The application simply creates a convenient way to browse a publicly available media database. The developer of this application has no affiliation with the content providers. The content provided can be removed at any time and we have no control over it. The developer assumes no liability and is not responsible for any legal issues caused by the misuse of this application.

No video files are stored in this repository, the application bundles open-sourced iptv-org playlist for quick startup, users can delete that playlist entry if they want to from their computer. If any links/channels in this application infringe on your rights as a copyright holder, they may be removed by sending a pull request or opening an issue. However, note that we have no control over the destination of the link, and just removing the link from the playlist will not remove its contents from the web. Note that linking does not directly infringe copyright because no copy is made on the site providing the link, and thus this is not a valid reason to send a DMCA notice to GitHub. To remove this content from the web, you should contact the web host that's actually hosting the content (not GitHub, nor the maintainers of this repository).

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

If you want to change any function, feel free to do. You could refactor, propose architecture changes, design assets, add new features, provide CI/CD things and build for other platforms. Basically, all changes that can improve this software are welcome.

Dependency versions are maintained in pyproject.toml and uv.lock. Use uv sync --frozen --dev for the locked development environment. After updating dependencies, regenerate the hash-pinned runtime installation file rather than editing it by hand:

uv export --frozen --no-dev --no-emit-project --output-file requirements.txt

Licensing

QiTV is licensed under MIT. The release downloads also contain other people's software, each under its own license. THIRD-PARTY-NOTICES.md lists them all, and the license texts are in licenses/ (both are inside the downloads too).

  • VLC (libVLC and its plugins): libVLC is licensed under the LGPL-2.1-or-later; some VLC plugins are under the GPL-2.0-or-later. QiTV ships VLC's own build unchanged. VLC's source code is at videolan.org/vlc and code.videolan.org/videolan/vlc.
  • Qt and PySide6: used under the LGPLv3. See the Qt licensing page.
  • Python: the CPython 3.14 runtime (PSF-2.0) and the libraries its build includes, such as OpenSSL (Apache-2.0), libffi, bzip2, xz, SQLite, Expat, mpdecimal, Zstandard and zlib. THIRD-PARTY-NOTICES.md lists each with its version and license.
  • Python libraries (each license as its package states it):
Library License
aiohttp Apache-2.0 AND MIT
m3u8 MIT
mpv GPLv2+ or LGPLv2.1+
orjson MPL-2.0 AND (Apache-2.0 OR MIT)
packaging Apache-2.0 OR BSD-2-Clause
pycryptodomex BSD, Public Domain
PyQtDarkTheme-fork MIT
PySide6 LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
python-vlc LGPL-2.1+
requests Apache-2.0
segno BSD License
tzlocal MIT
urllib3 MIT

QiTV 1.14.x bundled MPV (GPLv3); 2.0 does not.

  • Online services and media servers: subtitles from OpenSubtitles, film and series details from TMDB (QiTV uses TMDB and the TMDB APIs but is not endorsed, certified, or otherwise approved by TMDB), and your own Jellyfin or Emby server's titles, each over its own API; none of their code is part of QiTV.
  • Trademarks: Chromecast, Chromecast built-in and Google Cast are trademarks of Google LLC; QiTV casts through VLC's own Chromecast support. Emby is a trademark of its owner, and Jellyfin is the name of the Jellyfin project. QiTV is not affiliated with or endorsed by Google, Emby, the Jellyfin project or TMDB; each is named only to say what QiTV works with.

About

A cross-platform STB, Xtream, IPTV, Jellyfin and Emby player client

Topics

Resources

Stars

49 stars

Watchers

4 watching

Forks

Releases

Packages

Used by

Contributors

Languages