{"record":{"id":"812991b735fb5784","repo":"SubtitleEdit/subtitleedit","slug":"failed-to-initialize-vlc","errorCode":null,"errorMessage":"Failed to initialize VLC","messagePattern":"Failed to initialize VLC","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/ui/Logic/VideoPlayers/LibVlcDynamic/LibVlcDynamicNativeControl.cs","lineNumber":217,"sourceCode":"            }\n            _ownedChildHandle = IntPtr.Zero;\n            return parentHandle;\n        }\n    }\n\n    private void InitializeWithNativeWindow(IntPtr windowHandle)\n    {\n        if (_vlcPlayer == null)\n        {\n            return;\n        }\n\n        _vlcPlayer.LoadLib();\n\n        var err = _vlcPlayer.Initialize();\n        if (err < 0)\n        {\n            throw new InvalidOperationException(\"Failed to initialize VLC\");\n        }\n\n        _vlcPlayer.SetWindowHandle(windowHandle);\n\n        Dispatcher.UIThread.Post(() =>\n        {\n            Cursor = new Cursor(StandardCursorType.Arrow);\n            PlatformCursorManager.ForceArrowCursor();\n        }, DispatcherPriority.Background);\n    }\n\n    [DllImport(\"user32.dll\", CharSet = CharSet.Unicode, SetLastError = true)]\n    private static extern IntPtr CreateWindowExW(\n        uint dwExStyle,\n        string lpClassName,\n        string lpWindowName,\n        uint dwStyle,\n        int x,","sourceCodeStart":199,"sourceCodeEnd":235,"githubUrl":"https://github.com/SubtitleEdit/subtitleedit/blob/17a9f0748781032255db3526b7215d2fb891e3af/src/ui/Logic/VideoPlayers/LibVlcDynamic/LibVlcDynamicNativeControl.cs#L199-L235","documentation":"Thrown by LibVlcDynamicNativeControl.InitializeWithNativeWindow when LibVlcDynamicPlayer.Initialize() returns a negative value. Initialize() returns -1 if the native libvlc entry point 'libvlc_new' could not be resolved (library not loaded) OR if libvlc_new returned a null handle, meaning libVLC could not create a core instance. This is the wrapper's signal that the VLC native backend is unusable for the requested native-window embedding path.","triggerScenarios":"Called from CreateNativeControlCore during Avalonia NativeControlHost initialization. Specifically: _vlcPlayer.LoadLib() ran but LoadLibraryInternal() found no usable libvlc.so/dll/dylib on disk (so _libvlc_new delegate stays null), OR the .so/.dll was loaded but is the wrong architecture/bitness (x86 vs x64, arm64 vs x86_64) so libvlc_new returns IntPtr.Zero. Also when a VLC 4.x library is present whose exported symbol layout differs.","commonSituations":"VLC is not installed on the user's machine and LibVlcPath is unset; VLC installed but for the wrong architecture (32-bit VLC with 64-bit Subtitle Edit, or Intel-only VLC on Apple Silicon without translation); a broken/partial VLC install missing libvlc core plugins; running on a container/headless Linux without libvlc packaged; LibVlcPath points to a directory that has the file but the file is a stub or wrong arch.","solutions":["Install VLC matching the process architecture (64-bit VLC for a 64-bit build) from videolan.org, or set LibVlcDynamicPlayer.LibVlcPath to the directory containing the correct libvlc.","Verify the library loads with the right bitness: check the debug output lines 'Trying to load VLC from:' / 'Failed to load:' to see which candidate paths were tried and rejected.","On Linux, install the libvlc package (e.g. 'apt install vlc' or 'apt install libvlc5') so a system path in GetLibraryPaths resolves.","On macOS Apple Silicon, ensure a native arm64 VLC (or run under Rosetta with a matching arm64/x64 build pair) so libvlc.dylib exports resolve.","If deploying a bundled VLC, copy the full plugins/ tree alongside libvlc — a bare libvlc.so without its plugins causes libvlc_new to fail."],"exampleFix":"// before: relies on a system VLC being present\nLibVlcDynamicPlayer.LibVlcPath = string.Empty;\nvar player = new LibVlcDynamicPlayer();\n\n// after: point at a known-good, architecture-matched VLC directory before loading\n#if WINDOWS\nLibVlcDynamicPlayer.LibVlcPath = @\"C:\\Program Files\\VideoLAN\\VLC\";\n#elif LINUX\nLibVlcDynamicPlayer.LibVlcPath = \"/usr/lib\";\n#endif\nvar player = new LibVlcDynamicPlayer();\nif (!player.CanLoad())\n{\n    Se.Logger.Warn(\"VLC not available; falling back to another video player.\");\n    return null;\n}","handlingStrategy":"validation","validationCode":"// Probe the native backend before wiring it into the UI.\n// CanLoad() runs the full library search and returns false without throwing.\nvar player = new LibVlcDynamicPlayer();\nif (!player.CanLoad())\n{\n    // VLC unavailable — pick a different IVideoPlayer instead of letting\n    // InitializeWithNativeWindow throw later during native-control creation.\n    return SelectFallbackPlayer();\n}\nvar control = new LibVlcDynamicNativeControl(player);","typeGuard":null,"tryCatchPattern":"// CreateNativeControlCore already swallows this; if you call\n// InitializeWithNativeWindow directly, mirror that containment:\ntry\n{\n    InitializeWithNativeWindow(windowHandle);\n}\ncatch (InvalidOperationException ex) when (ex.Message == \"Failed to initialize VLC\")\n{\n    Se.LogError(ex, \"VLC native init failed; control will render without video.\");\n    // _isInitialized stays false; Render falls back to a black surface.\n}","preventionTips":["Call LibVlcDynamicPlayer.CanLoad() at player-selection time and fall back to another IVideoPlayer when it returns false.","Ship or point at an architecture-matched VLC (64-bit process needs 64-bit libvlc) and set LibVlcDynamicPlayer.LibVlcPath explicitly in your bootstrap.","Watch the 'Trying to load VLC from:' / 'Failed to load:' debug lines during setup to catch silent load failures before they surface as init errors.","Bundle the full VLC plugins/ directory alongside libvlc — core init fails without its plugin tree."],"tags":["vlc","libvlc","native-interop","video-player","platform","p-invoke"],"backgroundTag":null,"analyzedSha":"17a9f0748781032255db3526b7215d2fb891e3af","analyzedAt":"2026-08-13T18:11:43.374Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}