Playback problems · Theia: IPTV Player

Try this first

Click Playback status on the error card. A source that fails to refresh has the same button in Settings > Sources, and Check connection on any source’s card runs the same check whenever you like. It checks your internet, Theia’s VPN if you use one, your provider’s server and your account, then says which one is the problem. It never opens a stream to test. If it says your provider’s server is blocked on this network, ask your provider about it. If it says your internet provider may be blocking the stream server, sending Theia through a VPN usually fixes it, and Set up your VPN takes you there.

You can also play the same channel in another app, or on another device on the same network. If it fails there too, the problem is with your provider or your connection, and changing Theia won’t fix it.

When a channel won’t play

Theia retries on its own. After 2 seconds a card shows “Connecting to” the channel, with Cancel to go back to the channel you were on, then “Still trying”. When the channel comes in more than one quality, each gets about 8 seconds before Theia tries the next. After those come backup copies, which are other channels in the same source with the same guide id, and last the same channel on another source. The last one gets 15 seconds, then Theia stops and says why. A channel that’s gone or refused says so straight away.

When a backup copy is available, the Connecting and error cards have Try another copy. Backup copies show as Backup copy in Quality and feed, with Group channel variants on.

If channels fail to start when you switch quickly, raise Channel zapping delay in Settings > Playback. Theia then waits up to 2 seconds before the next channel opens.

What it says	Try
Past this source’s stream limit	The card says what’s using your streams. Close one of them with the button on the card. See Too many connections.
Your provider rejected the connection	Usually the connection limit is reached on another device, or the subscription has ended. Stop watching elsewhere, then Retry, or click Check account.
Can’t reach, followed by the server’s address	The server didn’t answer. Try again later, or click Playback status to see why.
This channel is gone from your provider’s list	Theia checks your provider’s list before it says this. Click Refresh playlist. Providers rename and remove channels.
Connected, but no video arrived for 10 seconds	The stream sent sound and no picture. Try another feed, as in Buffering and freezing.
This stream could not be decoded	Click Retry, or try another feed of the channel.
This channel uses a codec Theia can’t play	Try another feed of the channel, or Try safe mode on the card.
Stream failed because the VPN tunnel is down, or because the proxy isn’t answering	See Using a VPN.
The saved sign-in for this source cannot be read on this PC	Click Sign in again. This happens after moving to a new PC or restoring a backup.
Something went wrong opening this channel	Click Retry. If it keeps happening, send a report.

On a computer or phone, most error cards also have Copy details, and all of them have Report a problem. A TV has nowhere to paste, so its cards leave Copy details off. A channel that fails three times in a row gets a red dot in Live TV.

On a TV the card opens on Retry, and Left and Right move across its buttons. Up and Down still change channel, so you can keep zapping. OK presses the button you’re on, and Back leaves the player. The same goes for the cards that say Connecting, Reconnecting or Waiting for the VPN: the remote can reach every button on them.

A channel that was playing and then drops is handled differently. Theia reconnects on its own for up to ten minutes, holding the last picture with Try now and Stop. If your provider restarts the stream a few seconds behind live, Theia skips the seconds you already saw, so the scene doesn’t play twice.

Too many connections

Your plan allows a set number of streams at once, and every device counts: a TV box, a phone, another PC. In Theia, the player, the previews in Live TV, the guide and Home, a channel playing in the corner on a computer, each multiview tile and each scheduled recording use one. Faster channel switching and Check other feeds in the background in Settings > Playback borrow a spare one for a moment. Faster channel switching isn’t available on TVs.

Tell Theia your limit with Streams allowed on the source. See Getting started.
When the limit is reached in Theia, the card names what’s open and offers to close it. Go ahead tries anyway. To stop being asked, turn off Warn before going past the stream limit on the source. On a TV the card starts on Cancel, so a stray OK doesn’t go past your limit.
When your provider refuses the stream, Theia can’t see what’s using it. Check your other devices, then Retry.

Buffering and freezing

When a picture freezes, a Buffering tag shows over the last frame. Theia then waits for 5 seconds of video before it plays again, so a bad stretch becomes one short pause. If stalls keep coming, it waits a little longer each time, up to 15 seconds, and eases back once the stream is steady. The picture still counts as live.

Theia also measures how fast each copy of a channel arrives. When one can’t keep up, it moves to the fastest copy it knows, and stays put when every copy is just as slow, since each switch means reconnecting. If no copy keeps up and the channel has a lower quality one, Theia switches to it and says so, then goes back once the better copy holds up. Turn that off with Lower quality to stop buffering in Settings > Playback. Both need Group channel variants, below.

Other feeds. With Group channel variants on (Settings > Interface, on by default), a channel’s UHD, FHD, HD and SD copies are one row. If the feed keeps freezing, Theia switches to another and says so. It can also offer another channel showing the same game, while Offer to switch freezing streams in Settings > Playback is on. To choose yourself, right-click the video, or hold OK on a TV, and pick from Quality and feed.
Buffer duration in Settings > Playback starts at Off, which is quickest. A longer buffer rides out a server that sends in bursts. See Buffer duration.
Live stream format on an Xtream source’s page is TS by default. HLS (m3u8) holds up better through a VPN or a busy server.

Buffer duration

Settings > Playback > Buffer duration sets how much video Theia holds before the picture starts, and before it plays on after running dry. Off starts fastest.

A longer buffer rides out a choppy server that sends in bursts. Live TV arrives at broadcast speed, so the picture waits that long to start and plays that far behind live. It can’t fix a server that’s slower than real time. Theia’s smart buffering and feed switching handle that.

On a computer, type a length (45, 2 min or 1:30) or pick a preset: Off, 3, 5, 10, 15, 30, 60 or 120 seconds.
On Windows and Mac, the player menu has a Buffer line with - and + that move it a second at a time. It changes the stream you’re watching and saves the same setting, so Settings shows it too.
On a TV, - and + take bigger steps as the length grows. Press OK on the length for the presets.
Devices with less memory hold less: 30 seconds on sticks with up to 1.5 GB, and 60 on boxes with 2 to 3 GB. Computers and bigger boxes hold the full 2 minutes. Settings shows the limit.
In multiview, tiles share the buffer, so each holds less.
On iPhone and iPad, with a long buffer, Theia waits for it to refill on a slow provider instead of moving to another copy of the channel at once. A feed that has frozen still moves right away.
Previews in Live TV and the guide wait no more than 5 seconds, whatever the setting.
A change in Settings applies to the next channel you open.

Black screen, broken picture or no sound

Black screen or picture that won’t start, on a TV. Video output in Settings > Playback picks how the picture reaches the screen: Automatic uses direct video output for the smoothest picture, and switches to the app’s renderer on its own when you turn on subtitles or a channel needs it. If the picture still won’t show, set it to the app’s renderer yourself, or click Use the app’s renderer on the error card. Either way it takes effect the next time Theia starts, and Theia offers to close itself for you.
Green or broken picture. Set Video decoding to Safe mode in Settings > Playback, then to Software if that doesn’t help. The error card offers the same steps: Try safe mode, then Try software decoding. This isn’t available while direct video output is in effect, since it handles decoding on its own.
Lines across moving pictures. Try Deinterlace set to On. A TV doesn’t have this setting.
No sound. Check Audio track in the player’s controls. If you turned on Dolby and DTS passthrough without a receiver or soundbar, turn it off. On Android TV, Theia 0.9.2 and later keep passthrough off whatever the setting says, so a TV or soundbar that can’t decode the format never plays silence.
Sound out of step. Change Audio delay.
Quiet sound. Volume boost in Settings > Playback makes a quiet stream louder than full volume, up to 200%. Loud streams may distort.
Loud ads and quiet dialog. Turn on Even out loudness in Settings > Playback. It does nothing with Dolby and DTS passthrough on. A TV doesn’t have this setting.
Jerky motion. Turn on Match display refresh rate in Settings > Playback. It depends on the display: at 60 Hz, 25 and 50 fps channels still judder.

Stream stats in the player menu shows the formats, the buffer and dropped frames, and how playback has been going. Under Recent it says things like “Stopped to buffer 3 times in the last 5 min, longest 4 s” or “Delivery slowed twice”, and the Buffer line shows how full the buffer is, such as “12 of 30 s, filling”. On Windows and Mac its Buffer line has - and + too. On iPhone it’s Stream details in the More menu: a sheet that slides up from the bottom (drag it up for full height, or down to close) with the picture clear above it. On an upright iPhone, tap More on the picture. On iPad it opens as a popover beside the button.

Playback notices and history on a TV

When playback stops to buffer or video arrives slowly, a TV says Video stalled or Slow delivery over the picture and shows how much has buffered, such as 4 / 15 s. It describes what it sees. It doesn’t guess whether your Wi-Fi or your provider is the cause. If the feed keeps stalling, Change channel is the first thing to try, and Theia can offer another copy of the channel while Offer to switch freezing streams in Settings > Playback is on. In multiview each tile has its own notice, sized to fit a small picture.

Playback history in Settings > Playback lists recent buffering, feed changes and playback problems, newest first, with the time of each. Show playback logs, at the end of the player’s or a tile’s options, shows the same kind of list live for every channel that is playing. A problem report carries the history.

Using a VPN

A VPN keeps your viewing private from the network you’re on. Theia can send only its own traffic through a VPN or a proxy, or use a VPN app running for the whole PC. On a TV, use a VPN app for the whole TV, or a proxy. Steps for each service are in VPN setup. How you use a VPN has to follow the laws where you live and your provider’s terms.

The settings are in Settings > Network & VPN.

Test connection checks the VPN route and your address. Check a stream opens one channel briefly, when a connection is free.
Check my IP, at the top of the page, shows the public address and rough location the internet sees through Theia’s route. It asks a public connection check only when you click it, or once each time Theia opens with Check on start on.
When your device has its own VPN running and Theia’s own routing is off, the Network page says “Your device’s VPN carries the traffic.” That is a reading, not a setting: nothing to change.
When Theia sends its own traffic through a VPN or proxy, Leak protection starts on. Streams wait while that route is down, so nothing goes out without it, and the player says why.
“Couldn’t save the tunnel settings on this PC.” Restart Theia and try again.
“Couldn’t start the tunnel helper.” Windows Security or your antivirus may have blocked it. Open Windows Security > Virus & threat protection > Protection history and allow it on this device. See VPN setup.
“The tunnel helper isn’t running.” Try Test connection again.

These only happen on a computer. If the tunnel helper keeps failing, turn off Theia’s VPN setting and connect your VPN app for the whole PC instead.

When a source fails to check or refresh the way an internet provider block looks, its card offers Set up your VPN on its own, before you run any check.

If the channel list is slow to start during setup, Theia suggests a closer VPN server past a minute of nothing back. See What the first load does.

Sending a report to support

Open Settings > Support > Report a problem. It’s also on most error cards.
Say what went wrong. Leave Include recent logs on, and add your email if you’d like a reply.
Click Send report. You get a ticket code such as TH-7K2P. Quote it if you write to support@theiaplayer.com about the same problem.

Sign-ins, server addresses and channel names are taken out first, and What will be sent shows exactly what’s in it. A report also carries the short playback history that Stream stats shows, so support can see how playback was going. Nothing goes until you click Send report.

On a computer, to paste the details into an email instead, click Copy beside Copy diagnostics in Settings > Advanced. It copies recent logs and source details, with sign-ins, server addresses and channel names taken out. Stream stats in the player menu has Copy diagnostics too, for the stream on screen. A TV leaves both buttons off, and Back closes the stats.

If Theia closed unexpectedly, it asks “Theia closed unexpectedly last time. Send a report? You can see what’s in it before it goes.” when it next opens, on a TV too. Send a report opens the same form, and No thanks puts the question away. The form still carries the run that closed, until a report has gone, so putting the question away doesn’t lose it.

On a TV the form opens on What went wrong, and every field and button fits at large text. Send report reads Sending… while it works, and you get the answer even if you closed the form first. It tells you if the email address looks wrong, or if the report couldn’t be sent and why.

Please never email playlist links, server addresses or passwords. We don’t need them.