{"id":6890,"library":"sphinxcontrib-video","title":"Sphinxcontrib Video","description":"sphinxcontrib-video is a Sphinx extension that allows developers and technical writers to embed HTML5 videos (MP4, WebM, Ogg) directly into their Sphinx-generated documentation. It acts as a wrapper around the HTML5 `<video>` tag, exposing most of its parameters as directive options. The library is actively maintained, with the current stable version being 0.4.2, released on January 14, 2026, and typically follows a periodic release cadence.","status":"active","version":"0.4.2","language":"en","source_language":"en","source_url":"https://github.com/sphinx-contrib/video","tags":["sphinx","documentation","html5","video","extension"],"install":[{"cmd":"pip install sphinxcontrib-video","lang":"bash","label":"Install latest stable version"}],"dependencies":[{"reason":"This is a Sphinx extension and requires Sphinx to function.","package":"Sphinx","optional":false},{"reason":"Requires Python 3.9 or newer.","package":"Python","optional":false}],"imports":[{"note":"This entry should be added to the `extensions` list in your Sphinx project's `conf.py` file to enable the extension. There is no direct Python import for runtime use.","symbol":"sphinxcontrib.video","correct":"extensions = ['sphinxcontrib.video']"}],"quickstart":{"code":"# In conf.py\nimport os\n\nproject = 'My Video Project'\ncopyright = '2026, Your Name'\nextensions = [\n    'sphinxcontrib.video',\n]\nhtml_static_path = ['_static'] # Required if using local videos in a '_static' folder\n\n# In an .rst file (e.g., index.rst)\n..\n  _static/my_intro_video.mp4 is expected to exist\n  in your Sphinx project's _static directory.\n\nMy Documentation with Video\n===========================\n\nThis is an example of embedding a local HTML5 video:\n\n.. video:: _static/my_intro_video.mp4\n   :width: 60%\n   :autoplay:\n   :loop:\n   :controls:\n   :alt: An introductory video showing key features.\n   :caption: A short demonstration of the project setup.\n\nHere's an example of embedding an external video:\n\n.. video:: https://example.com/path/to/external_video.mp4\n   :poster: https://example.com/path/to/poster_image.jpg\n   :width: 500\n   :height: 300\n   :nocontrols:","lang":"python+rst","description":"To quickly use `sphinxcontrib-video`, first ensure it's installed. Then, add `'sphinxcontrib.video'` to the `extensions` list in your `conf.py`. If you plan to host local videos, configure `html_static_path` to point to your `_static` directory. Finally, use the `.. video::` reStructuredText directive in your documentation files, providing the video path and any desired HTML5 video attributes as options."},"warnings":[{"fix":"Ensure `extensions = ['sphinxcontrib.video']` is present and correct in your `conf.py`.","message":"The extension will not load if 'sphinxcontrib.video' is not correctly added to the 'extensions' list in `conf.py`. Common errors include typos or forgetting to add it after installation, leading to 'Could not import extension' errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Place local videos in your project's `_static` folder and confirm `html_static_path` is configured. Use relative paths like `_static/my_video.mp4` in the `video` directive.","message":"When embedding local videos, ensure their paths are correctly configured and accessible to Sphinx. Often, local video files should be placed in the `_static` directory and `html_static_path = ['_static']` should be set in `conf.py` for Sphinx to copy them to the build output. Incorrect paths will result in broken video embeds in the generated HTML.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If default styling is insufficient, add custom CSS to your Sphinx project (e.g., in `_static/custom.css` linked via `html_css_files` in `conf.py`) to target the video and caption HTML elements.","message":"Custom styling for video captions or alignment (e.g., centering) is not automatically handled by all Sphinx themes. While the `video` directive supports a `:caption:` option, its appearance and positioning often require custom CSS rules to achieve desired aesthetics, particularly for complex layouts or precise centering.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If video alignment is not as expected, try adding `:align: default` to your `video` directive.","message":"The default alignment behavior for videos without an explicit `:align:` option was changed in some versions. Previously, it might have defaulted to `left`. To ensure theme-defined alignment or no specific alignment, it's recommended to explicitly set `:align: default` if you observe unexpected alignment.","severity":"gotcha","affected_versions":"0.4.0 and later"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}