Media Plugins & Podcasting

Understanding the media plugin system for vlogs, podcasts, and multimedia content.

Media Plugin Architecture

djangocms-stories provides a comprehensive media plugin system designed for multimedia content publishing. This system is particularly useful for vlogs and podcasts that require more introspection on plugin contents than is generally available to standard Django CMS plugins.

Core Media Concepts

  • Media Attachment Plugins - Plugins that can be introspected for metadata

  • Media Placeholder - Dedicated media placeholder added to the Post model

  • Media Introspection - Automatic extraction of media metadata from external platforms

  • Template Integration - Specialized template tags for media handling

Design Philosophy

djangocms-stories provides only a generic interface to introspect media plugins but does not include plugins for specific media platforms, as these would be difficult to maintain as platforms change. The examples provided work at the time of writing but may require updates.

Supported Media Types

  • Video platforms (Vimeo, YouTube, custom players)

  • Audio content (podcasts, music, soundtracks)

  • Interactive media (360° videos, VR content)

  • Social media embeds with poster images

Base Classes and Mixins

MediaAttachmentPluginMixin

The foundation for creating media plugins:

from djangocms_stories.media.base import MediaAttachmentPluginMixin
from cms.models import CMSPlugin

class VimeoPlugin(MediaAttachmentPluginMixin, CMSPlugin):
    url = models.URLField('Video URL')

    _media_autoconfiguration = {
        'params': [
            re.compile(r'^https://vimeo.com/(?P<media_id>[-0-9]+)$'),
        ],
        'thumb_url': '%(thumb_url)s',
        'main_url': '%(main_url)s',
        'callable': 'vimeo_data',
    }
Required Implementation

Every media plugin must implement the media_url property:

@property
def media_url(self):
    """Return the primary media URL"""
    return self.url
Template Tags

djangocms-stories provides template tags for media handling:

  • media_images - Extract cover images from media plugins

  • media_plugins - Retrieve media plugins from placeholders

Building Media Plugins

Step-by-Step Process

  1. Create Plugin Model Inherit from CMSPlugin and add MediaAttachmentPluginMixin:

    class VimeoPlugin(MediaAttachmentPluginMixin, CMSPlugin):
    url = models.URLField('Video URL')

  2. Configure Media Autoconfiguration Define how to extract media information:

    _media_autoconfiguration = {
    'params': [
        re.compile(r'^https://vimeo.com/(?P<media_id>[-0-9]+)$'),
    ],
    'thumb_url': '%(thumb_url)s',
    'main_url': '%(main_url)s',
    'callable': 'vimeo_data',
}

  3. Implement Required Properties Provide media_url and any additional properties:

    @property
def media_url(self):
    return self.url

@property
def media_id(self):
    try:
        return self.media_params['id']
    except KeyError:
        return None

@property
def media_title(self):
    try:
        return self.media_params['title']
    except KeyError:
        return None

Complete Vimeo Example

import re
import requests
from cms.models import CMSPlugin
from djangocms_stories.media.base import MediaAttachmentPluginMixin

class VimeoPlugin(MediaAttachmentPluginMixin, CMSPlugin):
    url = models.URLField('Video URL')

    _media_autoconfiguration = {
        'params': [
            re.compile(r'^https://vimeo.com/(?P<media_id>[-0-9]+)$'),
        ],
        'thumb_url': '%(thumb_url)s',
        'main_url': '%(main_url)s',
        'callable': 'vimeo_data',
    }

    def __str__(self):
        return self.url

    @property
    def media_id(self):
        try:
            return self.media_params['id']
        except KeyError:
            return None

    @property
    def media_title(self):
        try:
            return self.media_params['title']
        except KeyError:
            return None

    @property
    def media_url(self):
        return self.url

    def vimeo_data(self, media_id):
        """Fetch video metadata from Vimeo API"""
        response = requests.get(
            f'https://vimeo.com/api/v2/video/{media_id}.json'
        )
        json_data = response.json()
        data = {}
        if json_data:
            data = json_data[0]
            data.update({
                'main_url': data['thumbnail_large'],
                'thumb_url': data['thumbnail_medium'],
            })
        return data

Plugin Registration

CMS Plugin Class

Register the plugin with Django CMS:

from cms.plugin_pool import plugin_pool
from cms.plugin_base import CMSPluginBase

@plugin_pool.register_plugin
class VimeoPlugin(CMSPluginBase):
    model = VimeoPlugin
    module = 'Media'
    name = 'Vimeo'
    render_template = 'media_app/vimeo.html'
Plugin Template

Create the rendering template:

<!-- media_app/vimeo.html -->
{% if instance.media_id %}
    <iframe
        src="https://player.vimeo.com/video/{{ instance.media_id }}?badge=0&autopause=0&player_id=0&app_id=2221"
        width="1920"
        height="1080"
        frameborder="0"
        title="{{ instance.media_title }}"
        allow="autoplay; fullscreen"
        allowfullscreen>
    </iframe>
{% endif %}

Template Integration

Media Placeholder Usage

The media placeholder must be rendered in templates to allow plugin addition:

<!-- post_detail.html -->
{% if not post.main_image_id %}
    <div class="blog-visual">
        {% render_placeholder post.media %}
    </div>
{% else %}
    <!-- Regular image display -->
{% endif %}
Media Images in Post Lists

Use the media_images template tag to show cover images:

<!-- post_list.html -->
{% load djangocms_stories %}

{% for post in postcontent_list %}
    {% media_images post as previews %}
    <article class="post-item">
        <div class="blog-visual">
            {% for preview in previews %}
                <img src="{{ preview }}" alt="Media preview" />
            {% endfor %}
        </div>
        <h3><a href="{{ post.get_absolute_url }}">{{ post.title }}</a></h3>
    </article>
{% endfor %}
Media Plugins Access

Retrieve media plugins programmatically:

<!-- Template usage -->
{% media_plugins post as media_content %}
{% for plugin in media_content %}
    <div class="media-item" data-type="{{ plugin.plugin_type }}">
        {% render_plugin plugin %}
    </div>
{% endfor %}

Podcast Integration

Podcast Episode Plugin

Create specialized podcast plugins:

class PodcastEpisodePlugin(MediaAttachmentPluginMixin, CMSPlugin):
    episode_title = models.CharField(max_length=200)
    episode_number = models.PositiveIntegerField()
    audio_url = models.URLField()
    duration = models.DurationField()
    transcript_url = models.URLField(blank=True)

    _media_autoconfiguration = {
        'thumb_url': '%(cover_image)s',
        'main_url': '%(audio_url)s',
        'callable': 'get_podcast_metadata',
    }

    def get_podcast_metadata(self):
        return {
            'title': self.episode_title,
            'duration': str(self.duration),
            'cover_image': self.get_cover_image_url(),
            'audio_url': self.audio_url,
        }
Podcast Player Template

Rich audio player interface:

<!-- podcast_player.html -->
<div class="podcast-player">
    <div class="episode-info">
        <h4>{{ instance.episode_title }}</h4>
        <span class="episode-meta">Episode {{ instance.episode_number }}</span>
        <span class="duration">{{ instance.duration }}</span>
    </div>

    <audio controls preload="metadata">
        <source src="{{ instance.audio_url }}" type="audio/mpeg">
        Your browser does not support the audio element.
    </audio>

    {% if instance.transcript_url %}
        <a href="{{ instance.transcript_url }}" class="transcript-link">
            View Transcript
        </a>
    {% endif %}
</div>

djangocms-video Support

Poster Attribute Integration

djangocms-video poster attributes are automatically supported:

# The poster field from djangocms-video plugins
# is automatically detected and included in media_images

{% media_images post as previews %}
<!-- This will include both custom media plugin images
     and djangocms-video poster images -->
Video Plugin Enhancement

Extend djangocms-video with media attachment capabilities:

from djangocms_video.models import VideoPlayer

class EnhancedVideoPlayer(MediaAttachmentPluginMixin, VideoPlayer):
    """Enhanced video player with media attachment features"""

    _media_autoconfiguration = {
        'thumb_url': '%(poster)s',  # Use existing poster field
        'main_url': '%(movie_url)s',
    }

    @property
    def media_url(self):
        return self.movie_url or self.movie.url