Skip to content

Expanded App section with comprehensive guide #91

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: webview-windows
Choose a base branch
from
Open

Expanded App section with comprehensive guide #91

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 98 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -198,17 +198,104 @@
- 👀 ``PauseOnLostFocus`` Pause playback on window loses focus
- 🔍 ``AllowZoom`` Allow zoom via `pinch action` or ``CTRL+Scroll``
- ❌ **App Errors**
- If the app does not start and instantly closes, check the error log in ``portable_config\errors-{date}.txt``
- ⚠️ **Common Issues**
- ❗ [WebView2](https://developer.microsoft.com/de-de/microsoft-edge/webview2/#download) not installed – Installed by default using the installer but may have failed
- 🌎 Unreachable Web UI. Make sure you can reach the web ui hosted [here](https://zaarrg.github.io/stremio-web-shell-fixes/).
- ⚙️ Invalid MPV configuration like ``mpv.conf``, ``input.conf`` or ``scripts``
- 📄 Invalid ``stremio-settings.ini``
- 🧩 Invalid ``extensions``
> **⏳ Note:** A default stremio-settings.ini can be found [here](https://github.com/Zaarrg/stremio-desktop-v5/blob/webview-windows/utils/stremio/stremio-settings.ini)
- ❌ **App Errors & Troubleshooting**
Copy link
Owner

@Zaarrg Zaarrg Jun 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lets use a level 2 heading this way it can be directly linked to: ## ❌ App Errors & Troubleshooting

- 📋 **Quick Fixes for Common Issues**
1. **Try F5 first** - Refreshes the page and fixes many display issues
2. **Try Ctrl+F5** - Clears cache and fixes persistent problems (including volume slider)
3. **Restart the app** - Close completely via Task Manager and restart
4. **Reboot PC** - Fixes sleep-related streaming server issues
Copy link
Owner

@Zaarrg Zaarrg Jun 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reboot wont really help with anything. If pc goes to sleep the Stremio Service (Server.js) is closed. Meaning restarting the app is enough as this starts the Stremio Service again.

- 🚀 **App Won't Start / Instantly Closes**
- **Check error logs:** ``portable_config\errors-{date}.txt`` for specific error messages
- **WebView2 Issues:**
Copy link
Owner

@Zaarrg Zaarrg Jun 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also might be worth adding as troubleshoot step to use the portable version of the app. As the portable version comes with webview2. As there is the case users with custom windows iso like tinyOS or some kinda of optimized windows version have webview fully disabled as the edge browser is almost always stripped away. Meaning even installing it via the installer wont help as other components are fully missing from the os. So the only working way is the portable version in such cases.

Maybe could be also added under the Advanced Troubleshooting section.

- ❗ **[WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) not installed** – Most common startup issue
- Download from [Microsoft WebView2 Runtime](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)
- Install the "Evergreen Standalone Installer"
- Restart computer after installation
- 🔄 **WebView2 corrupted:** Uninstall from "Add or Remove Programs" and reinstall
- 🚫 **Antivirus blocking:** Add Stremio folder to antivirus exclusions
- **Configuration Issues:**
- ⚙️ **Invalid ``stremio-settings.ini``:** Delete file and restart (default will be created)
- 📺 **Invalid MPV config:** Try deleting ``mpv.conf``, ``input.conf`` temporarily
- 🧩 **Extension conflicts:** Move extensions out of ``portable_config\extensions`` to test

- ⚫ **Black Screen Issues**
- **First try:** Press **F5** to refresh the page
- **If F5 doesn't work:** Press **Ctrl+F5** to clear cache (also fixes volume slider)
- **For persistent issues, add to ``mpv.conf``:**
```shell
vo=gpu
# Try one of these GPU settings:
gpu-api=vulkan
# OR
gpu-api=opengl
```
- **WebView2 GPU conflicts:** Run from Command Prompt:
```shell
cd %localAppData%\Programs\LNV\Stremio-5\
set WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--disable-gpu
stremio.exe
```
- **Alternative WebView2 fixes:**
```shell
set WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--use-angle=opengl
# OR try these:
--use-angle=swiftshader
--use-angle=vulkan
--use-angle=d3d11
--disable_direct_composition_video_overlays=1
```
- 🎵 **Volume Control Not Working**
- **Quick fix:** Press **Ctrl+F5** to refresh and clear cache
- **Alternative:** Close video, restart app, try again
- **Check:** Windows audio mixer - ensure Stremio isn't muted

- 📱 **"Device suddenly not support stream" Error**
- **Immediate fix:** Restart the application completely
- **Root cause:** Occurs after computer sleep/hibernate
Copy link
Owner

@Zaarrg Zaarrg Jun 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Root cause is the Stremio Service (server.js) not starting. In Stremio under settings > Streaming the url for the server is shown (localhost:11470). Meaning either the server did not start at all, so a app restart can help.

Or a server was already running on port 11470 e.g. someone has stremio 4 running as well. Meaning closing any other stremio app running then restarting the app will fix it.

One other root cause might be the server starting too late. This means the app starts trys to connect to the streaming url specified in settings but its not running yet. This then can be fixed by clicking on the Reload button in the settings so it trys to connect again.

(Sleep/hibernate seems to close the server or the connection that is why the sleep causes the not support msg)

- **Prevention:** Restart Stremio after waking computer from sleep
- **Check streaming server status:** Go to Settings > Streaming tab
- **Server should show:** Status "Online"
- **If offline:** Use Task Manager to close all Stremio processes, then restart

- 🌐 **Web UI Connection Issues**
- **Cannot reach Web UI:** Verify you can access the web interface hosted [here](https://zaarrg.github.io/stremio-web-shell-fixes/)
Copy link
Owner

@Zaarrg Zaarrg Jun 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Web UI has multiple url's as backup. First connection attempt is this, then this and lastly the offical one this

- **Streaming server offline:** Check Settings > Streaming - should show "Online"
- **Port conflicts:** Another Stremio instance might be running - check Task Manager
- **After sleep mode:** Always restart Stremio after computer wake-up

- 🐌 **Performance Issues**
- **High CPU/Memory:**
- Close other applications
- Reduce ``ThumbFastHeight`` setting or set to ``0``
- Update graphics drivers
- **Stuttering/Buffering:**
Copy link
Owner

@Zaarrg Zaarrg Jun 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also might be worth adding to check the hoster or url a user is trying to play. Most of the time buffering is caused by the hoster e.g. real debrid/torrentio. I also saw cases in which the isp was throttling the connection. Meaning even tho the hoster was fine users still got buffering as the isp detected the streaming.

- Try different GPU settings in ``mpv.conf``
- Check available storage space
- Disable browser hardware acceleration if conflicts occur

- 🔧 **Advanced Troubleshooting**
- **Complete reinstall:**
1. Uninstall app completely with user data
2. Verify ``%localAppData%\Programs\LNV\Stremio-5\`` is empty
3. Manually delete ``%temp%\stremio_updater`` if needed
4. Reinstall fresh copy
- **Cache issues:** Try Ctrl+F5 refresh to clear WebView2 cache
- **Multiple instances:** Use Task Manager to ensure no other Stremio processes
- 📁 **Log File Locations**
- **Main errors:** ``portable_config\errors-{date}.txt``
- **MPV logs:** ``portable_config\mpv-log.txt`` (if logging enabled)
- **Extension logs:** Check individual extension folders
- **Windows logs:** Event Viewer > Application logs (search "Stremio")
- 🆘 **Reporting Issues**
- Include error log from ``portable_config\errors-{date}.txt``
- Specify Windows version and graphics card
- Mention if issue occurs after sleep/wake cycle
- Note which F5/Ctrl+F5 method worked (if any)
- List recently changed settings or installed extensions
## 🎛️ **Mpv Configuration**
Enhance your Stremio experience by customizing the MPV player settings. Below are the key configuration files and guidelines to help you get started:
Expand Down