mirror of https://github.com/lektor/lektor-website.git

Ionuț Ciocîrlan
2020-03-20 11145a25bea4c81d818e2bfaec978126682651a2
Merge pull request #279 from runfalk/master

Added documentation about video FFmpeg support. Fixes #264.
1 files modified
1 files added
89 ■■■■■ changed files
content/docs/project/file/contents.lr 12 ●●●●● patch | view | raw | blame | history
content/docs/templates/videoops/contents.lr 77 ●●●●● patch | view | raw | blame | history
content/docs/project/file/contents.lr
@@ -197,3 +197,15 @@
url_prefix = /fr/
locale = fr
```
### `[attachment_types]`
Lektor does some basic attachment type detection based on file extension. This is what powers the `this.attachemnts.images` and `this.attachments.videos` attributes for instance. If the built-in map does not cover your file extension you can extend it or add new attachement types on a project by project basis.
Example:
```ini
[attachment_types]
; <.file-ext> = <type>
.gpx = gpx
.ogv = video
```
content/docs/templates/videoops/contents.lr
New file
@@ -0,0 +1,77 @@
title: Video Operations
---
body:
Just like [images](../imageops/), videos are separate files that are embedded into HTML files. Since they are media files, it's often desirable to read metadata or manipulate them in some way.
!! Video metadata access is powered by [FFmpeg](https://ffmpeg.org/). In order to use it FFmpeg must be installed on your system and detected by Lektor. If Lektor is unable to find FFmpeg you will see the error message `Unable to locate ffmpeg or ffprobe executable. Is it installed?` in your console output if you try to use functionality that requires it.
## Accessing videos
```html+jinja
{% for video in this.attachments.videos %}
  <div class="video"><video src="{{ video|url }}"></div>
{% endfor %}
```
Just like images you can also access them using `site.get('/myfolder').attachments.videos` or `site.get('/myfolder').attachments.get('examplevideo.mp4')`. Note that not all formats are detected as videos (see [attachments](../../content/attachments/)). If your format is not in the list you may still be able to get it detected as a video by adding it to your [Lektor project file](../../project/file/#[attachment_types]).
## Accessing metadata
Video objects are sub-classes of Attachments but with a few extra properties.
| Attribute | Description
| - | -
| `width` | Video height in pixels
| `height` | Video height in pixels
| `duration` | Video length as a [`datetime.timedelta`](https://docs.python.org/3/library/datetime.html) instance
Example:
```html+jinja
{% set video = this.attachments.videos.first() %}
<video src="{{ video|url }}">
<dl>
  <dt>Width:</dt>
  <dd>{{ video.width }} px</dd>
  <dt>Height:</dt>
  <dd>{{ video.height }} px</dd>
  <dt>Duration:</dt>
  <dd>{{ video.duration.total_seconds() }} s</dd>
</dl>
```
## Generating thumbnails
The main difference between video and image attachments is how thumbnails are handled. Since a video basically is a long sequence of images you must first choose where in the video the thumbnail should be generated. This is done using the `.frame() method. There are multiple ways of calling it:
| Method | Description
| - | -
| `frame()` | Use a frame from the middle of the video *(default)*
| `frame(seek: float)` | Fraction between 0.0 and 1.0 of the video duration from where to extract the frame. The value `0.5` means that the middle of the video will be used. It can be seen as a shorthand for `video.frame(video.duration * seek)`.
| `frame(seek: datetime.timedelta)` | Use a frame at the given seek distance from the beginning of the video. This is useful when you want to seek a fix time into a video.
Calling this method will return a `VideoFrame` instance, which is not usable by itself. It does however just like an image have a thumbnail method.
Example:
```html+jinja
{% set video = this.attachments.videos.first() %}
<img src="{{ video.frame().thumbnail(300, 200, mode="crop")|url }}">
<img src="{{ video.frame(0.1).thumbnail(300, 200, mode="crop")|url }}">
```
Note that unlike images it is not possible to get an URL to a video frame directly:
```html+jinja
{% set video = this.attachments.videos.first() %}
<img src="{{ video.frame()|url }}"> <!-- This is not valid -->
```
---
sort_key: 40
---
summary: Shows how templates can work with videos
---
version_added: 3.2