wagtailmedia

To serve user-uploaded files during development, ensure your urls.py includes the static helper for MEDIA_URL and MEDIA_ROOT.

Note: This is for development (DEBUG = True) only. In production, configure your web server (e.g., Nginx) to serve files from MEDIA_ROOT directly.

from django.conf import settings
from django.conf.urls.static import static

urlpatterns = (
    # ... the rest of your URLconf goes here ...
) + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Install wagtailmedia using pip. It is compatible with Wagtail 7.0 and above.

Requirements:

• Python (3.10 - 3.14)
• Django (5.2, 6.0, 6.1)
• Wagtail (7.0 - 8.0)

pip install wagtailmedia

To use media in a StreamField, you have two options:

1. Specific Chooser Blocks: Use the built-in AudioChooserBlock or VideoChooserBlock for simple selection.
2. Custom Media Block: Inherit from wagtailmedia.blocks.AbstractMediaChooserBlock and implement render_basic to define how the media (e.g., <video> or <audio> tags) is rendered in the frontend.

from wagtail import blocks
from wagtail.fields import StreamField
from wagtail.models import Page
from wagtailmedia.blocks import AudioChooserBlock, VideoChooserBlock

class BlogPage(Page):
    body = StreamField([
        ("audio", AudioChooserBlock()),
        ("video", VideoChooserBlock()),
    ])

You can extend the default media functionality by creating a custom model that inherits from wagtailmedia.models.AbstractMedia.

1. Define your custom model.
2. Update WAGTAILMEDIA["MEDIA_MODEL"] with the dotted path to your model.
3. (Optional) To customize the media model form, set WAGTAILMEDIA["MEDIA_FORM_BASE"] to the dotted path of your custom form class.

# settings.py
WAGTAILMEDIA = {
    "MEDIA_MODEL": "my_app.CustomMedia",
    "MEDIA_FORM_BASE": "my_app.forms.CustomMediaForm",
}

Use the construct_media_chooser_queryset hook to customize the list of media items shown in the media chooser view. The hook receives the current Media QuerySet and the request object, and must return a Media QuerySet.

from wagtail import hooks

@hooks.register("construct_media_chooser_queryset")
def show_my_uploaded_media_only(media, request):
    # Only show media uploaded by the current user
    media = media.filter(uploaded_by_user=request.user)
    return media

For Wagtail 8.0+, you can opt-in to the experimental API v3 (powered by django-ninja) by setting ENABLE_API_V3: True in your WAGTAILMEDIA settings. The media endpoint will be available at <v3 API root>/media/.

# settings.py
WAGTAILMEDIA = {
    "ENABLE_API_V3": True,
}

To expose media items through Wagtail's API v2, register the MediaAPIViewSet with your WagtailAPIRouter.

from wagtail.api.v2.router import WagtailAPIRouter
from wagtailmedia.api.views import MediaAPIViewSet

api_router = WagtailAPIRouter("wagtailapi")
api_router.register_endpoint("media", MediaAPIViewSet)

You can customize the base form used for media management by setting MEDIA_FORM_BASE in your wagtailmedia_settings. This allows you to provide a custom Django form class that will be used by get_media_form(). If no override is provided, BaseMediaForm is used by default, which includes specialized widgets for tags, file, and thumbnail.

# In your settings.py
WAGTAILMEDIA_SETTINGS = {
    'MEDIA_FORM_BASE': 'path.to.your.CustomMediaForm',
}

To restrict the types of files users can upload via the media forms, configure the allowed extensions in your wagtailmedia_settings. The get_media_form function will use these to set the accept attribute on the HTML file input. If no extensions are provided, it defaults to the browser's standard video/* or audio/* MIME types.

# In your settings.py
WAGTAILMEDIA_SETTINGS = {
    'VIDEO_EXTENSIONS': ['mp4', 'webm'],
    'AUDIO_EXTENSIONS': ['mp3', 'wav'],
}