Permalink
Browse files

Updated the documentation

  • Loading branch information...
1 parent affe752 commit 5a90555e711348f4eceebc23a94a225f540e4a34 @nmfm committed Nov 1, 2011
Showing with 147 additions and 24 deletions.
  1. +20 −15 docs/installation.rst
  2. +59 −4 docs/settings.rst
  3. +68 −5 docs/usage.rst
View
@@ -104,35 +104,40 @@ To crop an image and respect the subject location::
video conversion with ffmpeg
............................
-If installed ffmpeg is used for conversion of uploaded videos in multiple
-formats, resizing of video dimensions and capture of poster image from the
-video.
+If installed, `ffmpeg`_ can be used for the conversion of uploaded videos into multiple
+formats, resizing of video dimensions and capture of a screenshot to use as a poster image.
-The list of accepted video formats for upload is set in the setting bellow.
-When using ffmpeg this list should match the formats available for conversion.
+The list of accepted video formats for upload is defined in the ``FILER_SOURCE_VIDEO_FORMATS`` setting. Uploaded
+files with these extensions (do not include the leading dot) will be recognized by django-filer as video files.
+When using ffmpeg this list should match the formats available for conversion.
FILER_SOURCE_VIDEO_FORMATS = ('mp4', 'avi', 'wmv', 'mov', 'mpg')
-With ffmpeg available, when a file is upload it is converted to the formats in
-the output formats list.
+With `ffmpeg`_ available, django-filer is able to automatically convert uploaded videos to other formats. To define
+the list of formats to which thry should be conevrted to, set the ``FILER_VIDEO_FORMATS`` setting to a list of
+the correponding file extensions.
FILER_VIDEO_FORMATS = ('flv', 'mp4','webm')
By default the videos are converted maintaining the original video dimensions.
-For each video, in the admin interface it is possible to choose different
-dimensions, but if all videos should be resized to given dimensions, the
-setting bellow can be used.
+It is possible to choose different dimensions in the admin interface [REF] for each video,
+but if all videos should be resized to a preset dimension, the ``FFMPEG_TARGET_DIMENSIONS``
+setting can be used.
FFMPEG_TARGET_DIMENSIONS = "640x480"
-Parameters regarding the conversion quality can be adjusted in the setting
-FFMPEG_CMD, and parameters for the capture of the poster image can be adjusted
-in the setting GRABIMG_CMD.
+The value must be a string in the format "<width>x<height>". Leave it blank to revert to
+the default behaviour.
+
+Parameters regarding the conversion quality can be adjusted in the setting
+``FFMPEG_CMD``, and parameters for the capture of the poster image can be adjusted
+in the setting ``GRABIMG_CMD``. Check the `ffmpeg`_ documentation for a list of available
+options.
Cron setup for video conversion
-...............................
+-------------------------------
-Converting a video is a time consuming operation that cannot be done during
+Converting a video is a time consuming operation that cannot be done during
the upload of the file. When the video is uploaded it gets the conversion
status "new". A Django management command is provided for running the
conversion of all videos with "new" status.
View
@@ -44,11 +44,14 @@ directory should be served.
will be applied with the current date whenever a file is uploaded or moved
between public (without permission checks) and private (with permission
checks) storages.
-
+
Defaults to ``'filer.utils.generate_filename.by_date'``
-
+
``FILER_PUBLICMEDIA_THUMBNAIL_STORAGE``
Same as ``FILER_PUBLICMEDIA_STORAGE`` but for thumbnails
+
+``FILER_PUBLICMEDIA_FORMATS_STORAGE``
+ Same as ``FILER_PUBLICMEDIA_STORAGE`` but for automatically generated video files
``FILER_PRIVATEMEDIA_*``
------------------------
@@ -71,6 +74,9 @@ directory should be served.
``FILER_PRIVATEMEDIA_THUMBNAIL_ROOT`` and ``FILER_PRIVATEMEDIA_THUMBNAIL_URL``
as ``location`` and ``base_url``.
+``FILER_PRIVATEMEDIA_FORMATS_STORAGE``
+ Same as ``FILER_PRIVATEMEDIA_STORAGE`` but for automatically generated video files.
+
``FILER_PRIVATEMEDIA_SERVER``
The server backend to use to serve the private (with permission checks)
files with. The default serves the file entirely with django. This is not
@@ -81,7 +87,9 @@ directory should be served.
* ``filer.server.backends.xsendfile.ApacheXSendfileServer``
Defaults to ``filer.server.backends.default.DefaultServer``
-
+
+``FILER_PRIVATEMEDIA_FORMATS_SERVER``
+ Same as ``FILER_PRIVATEMEDIA_SERVER`` but for automatically generated video files
``FILER_PAGINATE_BY``
---------------------
@@ -105,4 +113,51 @@ Defaults to `False`
Regular users are not allowed to create new folders at the root level, only
subfolders of already existing folders, unless this setting is set to ``True``.
-Defaults to ``False``
+Defaults to `False`
+
+``FILER_SOURCE_VIDEO_FORMATS``
+------------------------------
+
+Formats recognized as video file formats. Used by djando-filer to identify video files when
+uploading a new file. The value should be a list of file extensions without the leading dot.
+
+Defaults to `('mp4', 'avi', 'wmv', 'mov', 'mpg')`
+
+``FILER_VIDEO_FORMATS``
+-----------------------
+
+Formats that uploaded video files will be automatically converted to (if the cronjob is set and
+ffmpeg available REF).
+
+Defaults to `('flv', 'mp4', 'webm')`
+
+``FFMPEG_CHECK_CMD``
+--------------------
+
+Command line executed to check video dimensions.
+
+Defaults to `"ffmpeg -i %(input_file)s"`
+
+``FFMPEG_CMD``
+--------------
+
+Command line executed to convert a video to a given format.
+
+Defaults to `"ffmpeg -i %(input_file)s -y -b 2326k -ar 44100 -ab 224k -ac 2 -f %(format)s %(dimensions)s %(target_file)s"`
+
+``GRABIMG_CMD``
+---------------
+
+Command line executed to grab a poster image for a video. The default is to grab a frame at 2s and
+create a pgn file.
+
+Defaults to `"ffmpeg -y -i %(input_file)s -vframes 1 -ss 00:00:02 -an -vcodec png -f rawvideo %(dimensions)s %(target_file)s"`
+
+``FFMPEG_TARGET_DIMENSIONS``
+----------------------------
+
+To resize the converted videos to fixed dimensions. The value should be in the <width>x<height> format.
+Leave blank to keep the original video dimensions.
+
+Defaults to `""`
+
View
@@ -4,7 +4,8 @@ Usage
======
``django-filer`` provides model fields to replace `djangos` own
-`django.db.models.FileField`_ and `django.db.models.ImageField`_.
+`django.db.models.FileField`_ and `django.db.models.ImageField`_, as well
+as an additional `FilerVideoField`.
The `django-filer` versions provide the added benefit of being able to manage
the files independently of where they are actually used in your content. As such
the same file can be used in multiple places without re-uploading it multiple
@@ -24,13 +25,14 @@ checksums.
company.logo.icons['64'] # or {{ company.logo.icons.64 }} in a template
-``FilerFileField`` and ``FilerImageField``
-------------------------------------------
+``FilerFileField``, ``FilerImageField`` and ``FilerVideoField``
+---------------------------------------------------------------
They are subclasses of `django.db.models.ForeignKey`_, so the same rules apply.
The only difference is, that there is no need to declare what model we are
-referencing (it is always ``filer.models.File`` for the ``FilerFileField`` and
-``filer.models.Image`` for the ``FilerImageField``).
+referencing (it is always ``filer.models.File`` for the ``FilerFileField``,
+``filer.models.Image`` for the ``FilerImageField`` and
+``filer.models.Video`` for the ``FilerVideoField``).
Simple example ``models.py``::
@@ -57,6 +59,67 @@ As with `django.db.models.ForeignKey`_ in general, you have to define a
non-clashing ``related_name`` if there are multiple ``ForeignKey`` s to the
same model.
+
+Video formats
+-------------
+
+Django-filer can be configured to automatically convert uploaded video
+files into alternative formats.
+
+This feature needs to be activated by setting up a cron job [REF] and configuring the
+desired output formats [REF].
+
+On the Django admin interface, videos have a group(?) "Conversion" with four fields:
+
+ - Conversion status -
+ - width, height
+ - conversion logo
+
+When a new video is uploaded, the conversion status is set to 'new'. This builds up a queue of video processing
+tasks.
+
+When the `convert_video` manage command is run, it will search for the next file with "new" status,
+change the status to "being processed" and execute the commands to generate the alternative versions and grab a poster
+image [REF].
+
+If all conversions are successful, the status will be set to "converted successfully". If any of the commands
+fail, it will be set to "Conversion failed".
+
+The output from these commands will be saved in the Conversion log field.
+
+You can change the dimensions of the generated videos for each file individually in the admin.
+Just input the new width and height into the respective fields and set the status to "new" to make sure it's processed
+with these new dimensions.
+
+To process again a video, reset it's status to "new" and run the convert_video manage
+command manually or wait for the scheduled task to execute.
+
+python
+.......
+
+vdeo.formats : lists all available alternative formats for a file. Only those
+files existing on disk
+{'url': url, 'format':ext, 'filepath':filepath}
+
+.original_format :
+
+returns a dictionary
+{'url': url, 'format': fmt, 'mimetype': mimetype}
+
+
+formats_html5 - default formats that should be recognized by browsers on the video tag
+
+format_flash - url if available, empty dict otherwise
+
+
+poster url of the poster image
+{'url': '', 'format':ext, 'filepath':''}
+
+
+
+convert - if you need to process the video programatically use this
+
+
templates
.........

0 comments on commit 5a90555

Please sign in to comment.