Skip to content

Commit 2694098

Browse files
khalwatkhalwat
committed
* Updated README.md
1 parent 58de6e9 commit 2694098

File tree

2 files changed

+71
-100
lines changed

2 files changed

+71
-100
lines changed

‎README.md‎

Lines changed: 70 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Transcoder plugin for Craft CMS 3.x
22

3-
Transcode videos to various formats, and provide thumbnails of the video
3+
Transcode video & audio files to various formats, and provide video thumbnails
44

55
Related: [Transcoder for Craft 2.x](https://github.com/nystudio107/transcoder)
66

@@ -24,90 +24,19 @@ If you have managed hosting, contact your sysadmin to get `ffmpeg` installed.
2424

2525
## Transcoder Overview
2626

27-
The Transcoder video allows you to take any locally stored video, and transcode it into any size, bitrate, framerate, and save it out as a web-ready `.mp4` video file.
27+
The Transcoder allows you to take any locally stored video, and transcode it into any size, bitrate, framerate, and save it out as a web-ready video in a variety of file formats.
2828

29-
It also allows you to get a thumbnail of the video in any size and at any timecode.
29+
It can also transcode audio files to any bitrate & sample rate, to a variety of file formats. It can even extract audio tracks from video files.
30+
31+
It also allows you to get a thumbnail of a video in any size and at any timecode, and can extract information about audio/video files such.
3032

3133
Finally, it lets you download an arbitrary file (such as the transcoded video) via a special download link.
3234

33-
If the source file has changed since the last time the video was encoded, it will re-encode the video and replace it.
35+
If the source file has changed since the last time the video/audio was transcoded, it will re-encode the file and replace it.
3436

3537
## Configuring Transcoder
3638

37-
The only configuration for Transcoder is in the `config.php` file, which is a multi-environment friendly way to store the default settings. Don't edit this file, instead copy it to `craft/config` as `transcoder.php` and make your changes there. Here's the default `config.php` file:
38-
39-
<?php
40-
/**
41-
* Transcoder plugin for Craft CMS 3.x
42-
*
43-
* Transcode videos to various formats, and provide thumbnails of the video
44-
*
45-
* @link https://nystudio107.com
46-
* @copyright Copyright (c) 2017 nystudio107
47-
*/
48-
49-
/**
50-
* Transcoder config.php
51-
*
52-
* Completely optional configuration settings for Transcoder if you want to
53-
* customize some of its more esoteric behavior, or just want specific control
54-
* over things.
55-
*
56-
* Don't edit this file, instead copy it to 'craft/config' as 'transcoder.php'
57-
* and make your changes there.
58-
*
59-
* Once copied to 'craft/config', this file will be multi-environment aware as
60-
* well, so you can have different settings groups for each environment, just as
61-
* you do for 'general.php'
62-
*/
63-
64-
return [
65-
66-
// The path to the ffmpeg binary
67-
"ffmpegPath" => "/usr/bin/ffmpeg",
68-
69-
// The path to the ffprobe binary
70-
"ffprobePath" => "/usr/bin/ffprobe",
71-
72-
// The options to use for ffprobe
73-
"ffprobeOptions" => "-v quiet -print_format json -show_format -show_streams",
74-
75-
// The path where the transcoded videos are stored
76-
"transcoderPath" => $_SERVER['DOCUMENT_ROOT'] . "/transcoder/",
77-
78-
// The URL where the transcoded videos are stored
79-
"transcoderUrl" => "/transcoder/",
80-
81-
// Default options for encoded videos
82-
"defaultVideoOptions" => [
83-
"fileSuffix" => ".mp4",
84-
"bitRate" => "800k",
85-
"frameRate" => 15,
86-
"width" => "",
87-
"height" => "",
88-
"sharpen" => true,
89-
// Can be "none", "crop", or "letterbox"
90-
"aspectRatio" => "letterbox",
91-
"letterboxColor" => "",
92-
// File format settings
93-
"fileSuffix" => ".mp4",
94-
"videoFormat" => "mp4",
95-
"videoCodec" => "libx264",
96-
],
97-
98-
// Default options for video thumbnails
99-
"defaultThumbnailOptions" => [
100-
"fileSuffix" => ".jpg",
101-
"timeInSecs" => 10,
102-
"width" => "",
103-
"height" => "",
104-
"sharpen" => true,
105-
// Can be "none", "crop", or "letterbox"
106-
"aspectRatio" => "letterbox",
107-
"letterboxColor" => "",
108-
],
109-
110-
];
39+
The only configuration for Transcoder is in the `config.php` file, which is a multi-environment friendly way to store the default settings. Don't edit this file, instead copy it to `craft/config` as `transcoder.php` and make your changes there.
11140

11241
## Using Transcoder
11342

@@ -116,8 +45,8 @@ The only configuration for Transcoder is in the `config.php` file, which is a mu
11645
To generate a transcoded video, do the following:
11746

11847
{% set transVideoUrl = craft.transcoder.getVideoUrl('/home/vagrant/sites/nystudio107/public/oceans.mp4', {
119-
"frameRate": 20,
120-
"bitRate": "500k",
48+
"videoFrameRate": 20,
49+
"videoBitRate": "500k",
12150
"width": 720,
12251
"height": 480
12352
}) %}
@@ -126,8 +55,8 @@ You can also pass in an `Asset`:
12655

12756
{% set myAsset = entry.someAsset.first() %}
12857
{% set transVideoUrl = craft.transcoder.getVideoUrl(myAsset, {
129-
"frameRate": 20,
130-
"bitRate": "500k",
58+
"videoFrameRate": 20,
59+
"videoBitRate": "500k",
13160
"width": 720,
13261
"height": 480
13362
}) %}
@@ -137,25 +66,23 @@ It will return to you a URL to the transcoded video if it already exists, or if
13766
In the array you pass in, the default values are used if the key/value pair does not exist:
13867

13968
{
140-
"bitRate" => "800k",
141-
"frameRate" => 15,
69+
"videoFormat" => "mp4",
70+
"videoBitRate" => "800k",
71+
"videoFrameRate" => 15,
14272
"aspectRatio" => "letterbox",
14373
"sharpen" => true,
144-
"fileSuffix" => ".mp4",
145-
"videoFormat" => "mp4",
146-
"videoCodec" => "libx264",
14774
}
14875

14976
These default values come from the `config.php` file.
15077

15178
If you want to have the Transcoder not change a parameter, pass in an empty value in the key/value pair, e.g.:
15279

153-
{% set transVideoUrl = craft.transcoder.getVideoUrl('/home/vagrant/sites/nystudio107/public/trimurti.mp4', {
80+
{% set transVideoUrl = craft.transcoder.getVideoUrl('/home/vagrant/sites/nystudio107/public/oceans.mp4', {
15481
"frameRate": "",
15582
"bitRate": ""
15683
}) %}
15784

158-
The above example would cause it to not change the frameRate or bitRate of the source movie (not recommended for client-proofing purposes).
85+
The above example would cause it to not change the frameRate or bitRate of the source video (not recommended for client-proofing purposes).
15986

16087
The `aspectRatio` parameter lets you control how the video aspect ratio is maintained when it is scaled:
16188

@@ -175,16 +102,60 @@ You can control the color of the letterboxed area (it's `black` by default) via
175102

176103
The `sharpen` option determines whether an unsharp mask filter should be applied to the scaled video.
177104

178-
The file format settings `fileSuffix`, `videoFormat`, and `videoCodec` are all preset to what you'll need to generate `.mp4` videos. Change these only if you know what you're doing.
105+
The file format setting `videoFormat` is preset to what you'll need to generate `mp4` videos, but it can also generate `webm` videos, or any other format that `ffmpeg` supports. See the `config.php` file for details
106+
107+
### Generating a Transcoded Audio File
108+
109+
To generate a transcoded audio File, do the following:
110+
111+
{% set transAudioUrl = craft.transcoder.getAudioUrl('/home/vagrant/sites/nystudio107/public/podcast.mp3', {
112+
"audioBitRate": "64k",
113+
"audioSampleRate": 22050,
114+
"audioChannels": 1
115+
}) %}
116+
117+
You can also pass in an `Asset`:
118+
119+
{% set myAsset = entry.someAsset.first() %}
120+
{% set transAudioUrl = craft.transcoder.getAudioUrl(myAsset, {
121+
"audioBitRate": "64k",
122+
"audioSampleRate": 22050,
123+
"audioChannels": 1
124+
}) %}
125+
126+
It will return to you a URL to the transcoded audio file if it already exists, or if it doesn't exist, it will return `""` and kick off the transcoding process (which can be somewhat lengthy for long audio files).
127+
128+
In the array you pass in, the default values are used if the key/value pair does not exist:
129+
130+
{
131+
"audioFormat" => "mp3",
132+
"audioBitRate" => "128k",
133+
"audioSampleRate" => "44100",
134+
"audioChannels" => "2",
135+
}
136+
137+
These default values come from the `config.php` file.
138+
139+
If you want to have the Transcoder not change a parameter, pass in an empty value in the key/value pair, e.g.:
140+
141+
{% set transVideoUrl = craft.transcoder.getVideoUrl('/home/vagrant/sites/nystudio107/public/trimurti.mp4', {
142+
"audioBitRate": "",
143+
"audioSampleRate": "",
144+
"audioChannels": ""
145+
}) %}
146+
147+
The above example would cause it to not change the audio of the source audio file at all (not recommended for client-proofing purposes).
148+
149+
The file format setting `audioFormat` is preset to what you'll need to generate `mp3` audio files, but it can also generate `m4a`, `ogg`, or any other format that `ffmpeg` supports. See the `config.php` file for details
179150

180151
### Getting Transcoding Progress
181152

182-
Transcoding of videos can take quite a bit of time, so Transcoder provides you with a way to get the status of any currently running transcoding operation via `craft.transcoder.getVideoProgressUrl()`. For example:
153+
Transcoding of video/audio files can take quite a bit of time, so Transcoder provides you with a way to get the status of any currently running transcoding operation via `craft.transcoder.getVideoProgressUrl()` or `craft.transcoder.getAudioProgressUrl()`. For example:
183154

184155
{% set myAsset = entry.someAsset.first() %}
185156
{% set videoOptions = {
186-
"frameRate": 60,
187-
"bitRate": "1000k",
157+
"videoFrameRate": 60,
158+
"videoBitRate": "1000k",
188159
"width": 1000,
189160
"height": 800,
190161
"aspectRatio": "none",
@@ -267,23 +238,23 @@ You can control the color of the letterboxed area (it's `black` by default) via
267238

268239
The `sharpen` option determines whether an unsharp mask filter should be applied to the scaled thumbnail image.
269240

270-
### Getting Information About a Video
241+
### Getting Information About a Video/Audio File
271242

272-
To get information about an existing video, you can use `craft.transcoder.getFileInfo()`:
243+
To get information about an existing video/audio file, you can use `craft.transcoder.getFileInfo()`:
273244

274-
{% set transVideoUrl = craft.transcoder.getFileInfo('/home/vagrant/sites/nystudio107/public/oceans.mp4') %}
245+
{% set fileInfo = craft.transcoder.getFileInfo('/home/vagrant/sites/nystudio107/public/oceans.mp4') %}
275246

276247
You can also pass in an `Asset`:
277248

278249
{% set myAsset = entry.someAsset.first() %}
279-
{% set transVideoUrl = craft.transcoder.getFileInfo(myAsset) %}
250+
{% set fileInfo = craft.transcoder.getFileInfo(myAsset) %}
280251

281252
This returns an array with two top-level keys:
282253

283254
* `format` - information about the container file format
284255
* `streams` - information about each stream in the container; many videos have multiple streams, for instance, one for the video streams, and another for the audio stream. There can even be multiple video or audio streams in a container.
285256

286-
Here's example output from `craft.transcoder.getFileInfo`:
257+
Here's example output from `craft.transcoder.getFileInfo()`:
287258

288259
[
289260
'streams' => [
@@ -416,6 +387,6 @@ The file must reside in the webroot (thus a URL or URI must be passed in as a pa
416387

417388
Some things to do, and ideas for potential features:
418389

419-
* The videos could potentially be saved in different formats (though `.mp4` really is "the" standard for video)
390+
* Add a simpler way to extract the most common video/audio info from a file
420391

421392
Brought to you by [nystudio107](https://nystudio107.com)

‎composer.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "nystudio107/craft3-transcoder",
3-
"description": "Transcode videos to various formats, and provide thumbnails of the video",
3+
"description": "Transcode video & audio files to various formats, and provide video thumbnails",
44
"type": "craft-plugin",
55
"version": "1.0.1",
66
"keywords": [

0 commit comments

Comments
 (0)