wagtailvideos
Based on wagtailimages. The aim was to have feature parity with images but for html5 videos. Includes the ability to transcode videos to a html5 compliant codec using ffmpeg and also the ability to add and manage VTT text tracks for subtitles/captions.
Requirements
Wagtail >= 6.3 (for older wagtail version see the tags)
ffmpeg (optional, for transcoding)
Installing
Install using pypi
pip install wagtailvideosAdd wagtailvideos to your installed apps.
INSTALLED_APPS = [
'wagtailvideos',
]Using
On a page model:
Implement as a ForeignKey relation, same as wagtailimages.
from django.db import models
from wagtail.admin.edit_handlers import FieldPanel
from wagtail.core.fields import RichTextField
from wagtail.core.models import Page
from wagtailvideos.edit_handlers import VideoChooserPanel
class HomePage(Page):
body = RichtextField()
header_video = models.ForeignKey('wagtailvideos.Video',
related_name='+',
null=True,
on_delete=models.SET_NULL)
content_panels = Page.content_panels + [
FieldPanel('body'),
VideoChooserPanel('header_video'),
]In a Streamfield:
A VideoChooserBlock is included
from wagtail.admin.edit_handlers import StreamFieldPanel
from wagtail.core.fields import StreamField
from wagtail.core.models import Page
from wagtailvideos.blocks import VideoChooserBlock
class ContentPage(Page):
body = StreamField([
('video', VideoChooserBlock()),
])
content_panels = Page.content_panels + [
StreamFieldPanel('body'),
]In template:
The video template tag takes one required postitional argument, a video field. All extra attributes are added to the surrounding <video> tag. The original video and all extra transcodes are added as <source> tags.
{% load wagtailvideos_tags %}
{% video self.header_video autoplay controls width=256 %}Jinja2 extensions are also included.
How to transcode using ffmpeg:
Using the video collection manager from the left hand menu. In the video editing section you can see the available transcodes and a form that can be used to create new transcodes. It is assumed that your compiled version of ffmpeg has the matching codec libraries required for the transcode.
Disable transcode:
Transcode can be disabled using the WAGTAIL_VIDEOS_DISABLE_TRANSCODE setting.
# settings.py
WAGTAIL_VIDEOS_DISABLE_TRANSCODE = TrueModify maximum file size:
Maximum file size that can be uploaded is defaulted to 1GB. This can be overriden using the WAGTAILVIDEOS_MAX_UPLOAD_SIZE setting
# settings.py
WAGTAILVIDEOS_MAX_UPLOAD_SIZE = 1024*1024*1024Chunked uploads (optional):
Chunked uploads are disabled by default. If enabled, uploads are split into multiple requests and reassembled server-side. This is useful when running behind proxies/CDNs that enforce per-request body limits (for example, Cloudflare free plan limits).
Set WAGTAILVIDEOS_UPLOAD_CHUNK_SIZE (in bytes) to enable chunking for the multiple-upload admin screen.
# settings.py
# 95MB chunks to stay below 100MB per-request limits
WAGTAILVIDEOS_UPLOAD_CHUNK_SIZE = 95 * 1024 * 1024Modify Thumbnail extension:
The automatically generated Thumbnail extension can be modified using the WAGTAIL_VIDEOS_THUMBNAIL_EXTENSION setting. Default value is jpg
# settings.py
WAGTAIL_VIDEOS_THUMBNAIL_EXTENSION = 'webp'Custom Video models:
Same as Wagtail Images, a custom model can be used to replace the built in Video model using the WAGTAILVIDEOS_VIDEO_MODEL setting.
# settings.py
WAGTAILVIDEOS_VIDEO_MODEL = 'videos.AttributedVideo'
# app.videos.models
from django.db import models
from modelcluster.fields import ParentalKey
from wagtailvideos.models import AbstractVideo, AbstractVideoTranscode
class AttributedVideo(AbstractVideo):
attribution = models.TextField()
admin_form_fields = (
'title',
'attribution',
'file',
'collection',
'thumbnail',
'tags',
)
class CustomTranscode(AbstractVideoTranscode):
video = models.ForeignKey(AttributedVideo, related_name='transcodes', on_delete=models.CASCADE)
class Meta:
unique_together = (
('video', 'media_format')
)
class CustomTrackListing(AbstractTrackListing):
video = models.OneToOneField(AttributedVideo, related_name='track_listing', on_delete=models.CASCADE)
class CustomVideoTrack(AbstractVideoTrack):
listing = ParentalKey(CustomTrackListing, related_name='tracks', on_delete=models.CASCADE)Future features
Some docs
Richtext embed
Transcoding via external service rather than ffmpeg
3 maintainers
Metadata
3 maintainers
Release files for wagtailvideos 7.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| wagtailvideos-7.3.1.tar.gz | 85.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| wagtailvideos-7.3.1-py2.py3-none-any.whl | Python 3, Python 2 | none | any | Details |
Total release size: 199.9 kB
Release files / wagtailvideos-7.3.1.tar.gz
| Download URL | wagtailvideos-7.3.1.tar.gz |
|---|---|
| Size | 85.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e89ab966e3b7948081e46f757cacb726f090bd53df88105b6c20289b1db37525
|
|
BLAKE2b-256 checksum How to use checksums |
97867bb5f158a1a79f8874d2045365a686ca71afac5361bf2c36b12d922bbb52
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 4, 2026.
Transparency logRelease files / wagtailvideos-7.3.1-py2.py3-none-any.whl
| Download URL | wagtailvideos-7.3.1-py2.py3-none-any.whl |
|---|---|
| Size | 114.6 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
cc2316b536f3580c4b77bef08302a828814e73eaf912ac6f9430dd931dd9b573
|
|
BLAKE2b-256 checksum How to use checksums |
499876ffa62d7d6862a2f997b06eaab43210988502e4ee88f7330e7d1390d3e9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 4, 2026.
Transparency log
