Skip to main content

​
Common Playback Issues

This error typically appears briefly when starting a video.Solutions:
1

Wait 5 Seconds

The video should start playing automatically after a brief moment
2

Press Play

If waiting doesn’t work, manually press the play button
Additional causes:
  • USB audio device attached: Some users report this error only occurs when USB audio devices are connected. Try disconnecting USB audio devices.
  • Full disk storage: Check if your device storage is full. Free up space by clearing cache or uninstalling unused apps.
This is usually a temporary initialization issue and resolves itself within seconds.
This means your device doesn’t support the selected video codec (usually AV01).Solution:
1

Open Format Settings

Press the HQ button in the bottom-left corner of the player
2

Select Video Formats

Choose Video formats from the menu
3

Change Codec

Select anything other than AV01 - choose VP9 or AVC instead
AV01 is NOT supported on most devices, especially those manufactured before 2020. VP9 is the best choice for most Android TV devices.
See the Video Codecs guide for more information on choosing the right codec.
Currently a known bug when watching unlisted videos or your own videos.Status: This is a confirmed bug that’s being worked on.Workaround: Use the official YouTube app for unlisted content, or use casting from your phone.
This occurs when your IP address range is blocked by YouTube for unauthenticated viewing.Solutions:
  1. Sign in to your account: This usually resolves the issue immediately
  2. Change your network: Try a different internet connection
  3. Wait it out: Temporary blocks may be lifted after some time
  4. Use VPN: Change your IP address (may be against YouTube’s ToS)
This is a YouTube-side restriction, not a SmartTube issue. Your IP range might be temporarily or permanently flagged.

​
Buffering Issues

​
Videos Buffer Excessively

Buffering issues are not specific to SmartTube - other unofficial YouTube apps report the same problems. This appears to be server-side discrimination by YouTube.
Try these in-app adjustments:
  • Reduce resolution: Lower video quality temporarily
  • Change codec to AVC: Press HQ button > Video formats > AVC
  • Increase buffer size: Go to Settings > Video player > Buffer size and select High
  • Restart video: Hit back button and play the video again
Check your network connection:
  • Test your internet speed at fast.com
  • Ensure you have at least 5 Mbps for HD content
  • Try connecting via Ethernet instead of WiFi
  • Restart your router
  • Move closer to your WiFi router if using wireless
Buffer setting recommendation: Use High buffer for best performance. Higher buffer preloads more video, smoothing out network issues. RAM usage increase is minimal.

​
Installation Problems

Common causes:
  1. Disk space is full
    • Free up at least 200 MB of storage
    • Clear cache from other apps
    • Uninstall unused apps
  2. APK download corrupted
    • Download the APK again
    • Ensure stable internet connection during download
    • Verify file size is reasonable (usually 60-80 MB)
  3. Unknown sources blocked
    • Enable “Unknown sources” for your file manager/downloader
    • See Installation guide for device-specific steps
This happens when SmartTube is installed to external storage.Solution:
1

Uninstall SmartTube

Remove the current installation
2

Check Storage Settings

Go to device settings and ensure apps install to internal memory by default
3

Reinstall

Install SmartTube again - it should now go to internal storage
SmartTube MUST be installed to internal memory, not SD card or external storage, or it will crash.
If you downloaded the APK but can’t find it:
  • Use a file manager app like FX File Explorer
  • Check the Downloads folder
  • Android’s built-in file manager often doesn’t work properly
  • Avoid FileCommander (it’s ad-infested)

​
App Crashes and Freezes

This is typically a firmware or Android OS issue, not SmartTube-specific.Potential causes:
  • Buggy firmware
  • Custom ROM issues
  • Hardware problems
Troubleshooting steps:
1

Reboot Device

Turn off your Android TV completely and turn it back on
2

Clear Cache

Go to Settings > Apps > SmartTube > Clear cache (not Clear data)
3

Reinstall App

Uninstall and reinstall SmartTube
4

Factory Reset (Last Resort)

If all else fails, factory reset your device (backup data first!)
This issue is nearly impossible for the developer to debug since it’s device/firmware-specific. If using a custom ROM, the ROM might be buggy.
See “App Installed but Crashes on Opening” above - usually caused by installation to external storage.

​
Playback Performance Issues

Most TVs and TV boxes do not have hardware support for AV01 codec (too new).Solution: Switch to VP9 or AVC codec (see “Video profile is not supported” section above)
AV01 hardware support started appearing in devices from 2020 onwards. Most devices still don’t support it.
If VP9 videos play poorly:
  • Your device may lack VP9 hardware support
  • High resolutions (4K) require official hardware support
  • Cheap TV boxes without official 4K support will struggle
Solution: Switch to AVC codec, which is supported on all devices
Known issue when playing videos at speeds other than 1x.Status: Currently cannot be fixed. This is a limitation of the video playback engine.Workaround: Use normal playback speed (1x) for smooth playback.
When you jump back in a video, SmartTube must rebuffer.Status: This is current behavior and may be improved in future updates.Workaround: Minimize seeking backwards, or use higher buffer setting to reduce rebuffering time.

​
Search Issues

Recent updates to “Google app for Android TV” can cause voice search failures.Solution:
1

Open App Settings

Go to Settings > Apps > Google app for Android TV
2

Uninstall Updates

Select Uninstall updates to revert to the original version
3

Test Search

Try voice search again - it should now work

​
Getting Additional Help

If your issue isn’t covered here:
  1. Check the FAQ for more questions and answers
  2. Search the README using Ctrl+F / ⌘F
  3. Join the Telegram support group (English only)
  4. Report issues on GitHub

Build docs developers (and LLMs) love

Get started for freeTalk to us