Frank Seitz
and 1 contributors

NAME

Prty::FFmpeg - Konstruiere eine FFmpeg-Kommandozeile

BASE CLASS

Prty::Hash

DESCRIPTION

FFmpg Online-Dokumentation: https://www.ffmpeg.org/ffmpeg-all.html

Ein Objekt der Klasse repräsentiert eine ffmpeg-Kommandozeile. Die Klasse verfügt einerseits über elementare (Objekt-)Methoden, um eine solche Kommandozeile sukzessive aus Eingabe- und Ausgabe-Dateien, Optionen, Filtern usw. zu konstruieren und andererseits höhere (Klassen-)Methoden, die eine vollständige Kommandozeile zur Erfüllung eines bestimmten Zwecks unter Rückgriff auf die elementaren Methoden erstellen. Die höheren Methoden Methoden befinden sich im Abschnitt "Klassenmethoden (vollständige Kommandozeilen)".

METHODS

Konstruktor

new() - Konstruktor

Synopsis

    $cmd = $class->new;

Description

Instantiiere ein FFmpeg-Kommando-Objekt und liefere eine Referenz auf dieses Objekt zurück.

Objektmethoden

command() - Kommandozeile als Zeichenkette

Synopsis

    $str = $cmd->command;

Description

Liefere das Kommando als Zeichenkette.

input() - Eingabe-Datei als Objekt

Synopsis

    $fil = $cmd->input($i);

Description

Instantiiere Eingabe-Datei $i als Prty::File-Objekt und liefere dieses zurück. Das Objekt wird gecachted.

suffix() - Suffix Ausgabe-Datei

Synopsis

    $str = $cmd->suffix;

Description

Liefere den Suffix für eine Ausgabedatei. Der Suffix ist eine Zeichenkette der Form

    NAME-WIDTH-HEIGHT-START-STOP

wobei Komponenten fehlen können, die nicht definiert sind.

Kommandozeile konstruieren

addOption() - Füge Option hinzu

Synopsis

    $cmd->addOption($opt);
    $cmd->addOption($opt=>$val);

Description

Ergänze die Kommandozeile um die Option $opt und (optional) den Wert $val. Die Methode liefert keinen Wert zurück.

Examples

Option ohne Wert:

    $cmd->addOption('-y');
    =>
    -y

Option mit Wert:

    $cmd->addOption(-i=>'video/GOPR1409.mp4');
    =>
    -i 'video/GOPR1409.mp4'

addInput() - Füge Input-Option hinzu

Synopsis

    $cmd->addInput($input);

Description

Ergänze das Kommando um Input $input, sofern $input einen Wert hat. Die Methode liefert keinen Wert zurück.

Examples

Dateiname:

    $cmd->addInput('video/GOPR1409.mp4');
    =>
    -i 'video/GOPR1409.mp4'

Muster:

    $cmd->addInput('img/*.jpg');
    =>
    -i 'img/*.jpg'

Undefiniert:

    $cmd->addInput(undef);
    =>

addFilter() - Füge Filter-Option hinzu

Synopsis

    $cmd->addFilter($opt,\@filter,$sep);

Description

Ergänze das Kommando um Filter-Option $opt mit den Filtern @filter und dem Trenner $sep (Komma oder Semikolon).

Examples

Video Filter-Chain:

    $cmd->addFilter(-vf=>['crop=1440:1080','scale=720*a:720']);
    =>
    -vf 'crop=1440:1080,scale=720*a:720'

addStartStop() - Füge Optionen für Zeitbereich hinzu

Synopsis

    $cmd->addStartStop($start,$stop);

Description

Ergänze das Kommando um Optionen, die den Zeitbereich auf den Bereich $start und $stop eingrenzen.

Examples

Nur Start-Zeitpunkt:

    $cmd->addStartStop(5.5);
    =>
    -ss 5.5

Nur Ende-Zeitpunkt:

    $cmd->addStartStop(undef,20.5);
    =>
    -t 20.5

Start- und Ende-Zeitpunkt:

    $cmd->addStartStop(5.5,20.5);
    =>
    -ss 5.5 -t 20.5

addBitrate() - Füge Bitrate-Option hinzu

Synopsis

    $cmd->addBitrate($bitrate);

Description

Ergänze das Kommando um eine allgemeine Bitrate-Option mit Suffix 'k' (= kb/s). Ist die Bitrate 0, '' oder undef, wird die Option nicht hinzugefügt.

Examples

Bitrate von 10000k:

    $cmd->addBitrate(10000);
    =>
    -b 10000k

addOutput() - Füge Output-Argument hinzu

Synopsis

    $cmd->addOutput($output);

Description

Ergänze das Kommando um Output $output. Die Methode liefert keinen Wert zurück.

Examples

Dateiname:

    $cmd->addOutput('video/GOPR1409.mp4');
    =>
    'video/GOPR1409.mp4'

Muster:

    $cmd->addOutput('img/%06d.jpg');
    =>
    'img/%06d.jpg'

addString() - Füge Zeichenkette am Ende hinzu

Synopsis

    $cmd->addString($str);

Description

Füge Zeichenkette $str am Ende der Kommandozeile hinzu, mit einem Leerzeichen als Trenner.

Example

Kommando nach Objekt-Instantiierung:

    $cmd->addString('ffprobe');
    =>
    ffprobe

prependString() - Füge Zeichenkette am Anfang hinzu

Synopsis

    $cmd->prependString($str);

Description

Füge Zeichenkette $str am Beginn der Kommandozeile hinzu. Ein Leerzeichen wird automatisch hinzugefügt.

Example

Kommando voranstellen:

    $cmd->prependString('ffplay -autoexit');
    =>
    ffplay -autoexit ...

Filter

cropFilter() - Liefere Crop-Filter

Synopsis

    $str = $cmd->cropFilter($width,$height);
    $str = $cmd->cropFilter($width,$height,$xOffset,$yOffset);

Description

Erzeuge eine Crop-Filter-Spezifikation für die angegebenen Argumente und liefere diese zurück.

Examples

Nur Breite und Höhe:

    $cmd->cropFilter(1280,720);
    =>
    'crop=1280:720'

Breite, Höhe, X-Offset, Y-Offset:

    $cmd->cropFilter(1280,720,240,0);
    =>
    'crop=1280:720:240:0'

scaleFilter() - Liefere Scale-Filter

Synopsis

    $str = $cmd->scaleFilter($width,$height);
    $str = $cmd->scaleFilter("$width:$height");

Description

Erzeuge eine Crop-Filter-Spezifikation für die angegebenen Argumente und liefere diese zurück.

Sind die Argumente undefiniert, wird eine leere Liste geliefert.

Examples

Breite und Höhe als getrennte Argumente:

    $cmd->scaleFilter(1280,720);
    =>
    'scale=1280:720'

Breite und Höhe in einem Argument:

    $cmd->scaleFilter('1280:720');
    =>
    'scale=1280:720'

Undefiniertes Argument:

    @filter = $cmd->scaleFilter(undef);
    =>
    ()

fpsFilter() - Liefere Fps-Filter

Synopsis

    $str = $cmd->fpsFilter($fps);

Description

Erzeuge eine Fps-Filter-Spezifikation und liefere diese zurück. Ist das Argument undef, liefere eine leere Liste.

Examples

Argument:

    $cmd->fpsFilter(24);
    =>
    'fps=24'

Undefiniertes Argument:

    @filter = $cmd->fpsFilter(undef);
    =>
    ()

framestepFilter() - Liefere Framestep-Filter

Synopsis

    $str = $cmd->framestepFilter($fps);

Description

Erzeuge eine Framestep-Filter-Spezifikation und liefere diese zurück. Ist das Argument undef, liefere eine leere Liste.

Examples

Argument:

    $cmd->framestepFilter(4);
    =>
    'framestep=4'

Undefiniertes Argument:

    @filter = $cmd->framestepFilter(undef);
    =>
    ()

Ausgabe-Datei-Eigenschaften (Getter/Setter)

outName() - Setze/Liefere Bezeichnung Ausgabe-Datei

Synopsis

    $cmd->outName($name);
    $name = $cmd->outName;

Description

Setze oder liefere die Bezeichnung für die Ausgabe-Datei. Die Angabe wird für den Suffix der Ausgabe-Datei genutzt.

outSize() - Setze/Liefere Breite und Höhe Video-Ausgabe

Synopsis

    $cmd->outSize($width,$height);
    ($width,$height) = $cmd->outSize;

Description

Setze oder liefere die Höhe und Breite der Video-Ausgabe. Die Angabe wird für den Suffix der Video-Ausgabe-Datei genutzt.

outStart() - Setze/Liefere Start-Zeitpunkt

Synopsis

    $cmd->outStart($s);
    $s = $cmd->outStart;

Description

Setze oder liefere den Start-Zeitpunkt der Ausgabe. Die Angabe wird für den Suffix der Ausgabe-Datei genutzt.

outStop() - Setze/Liefere Stop-Zeitpunkt

Synopsis

    $cmd->outStop($s);
    $s = $cmd->outStop;

Description

Setze oder liefere den Stop-Zeitpunkt der Ausgabe. Die Angabe wird für den Suffix der Ausgabe-Datei genutzt.

Klassenmethoden (vollständige Kommandozeilen)

imagesToVideo() - Füge Bild-Sequenz zu einem Video zusammen

Synopsis

    $cmd = $class->imagesToVideo($pattern,$output,@opt);

Description

Generiere ein ffmpeg-Kommando zum Zusammenfügen der Bilder $pattern zu Video $output und liefere dieses Kommando zurück.

Arguments

$pattern

Pfad-Muster der Bilder. Enthält das Pfad-Muster einen Stern (*), wird -pattern_type glob gewählt.

Beispiele:

    'img/%06d.jpg' => -i 'img/%06d.jpg'
    'img/*.jpg'    => -pattern_type glob -i 'img/*.jpg'
$output

Name der generierten Video-Datei.

Options

-audio => $file (Default: undef)

Erzeuge einen Audio-Stream aus Audio-Datei $file.

-duration => $duration (Default: undef)

Beende die Ausgabe, wenn die Dauer $duration erreicht ist.

-framerate => $n (Default: 8)

Anzahl Bilder pro Sekunde.

-loop => $bool (Default: 0)

Wiederhole die Bildserie zyklisch.

-play => 0|1|2 (Default: 0)

Zeige das generierte Video im Player an, statt es in einer Datei zu speichern. Bei -play=>2 bleibt das Fenster des Players offen, bis es per Hand geschlossen wird.

-preset => $preset (Default: undef)

Satz an vorgewählten Optionen, für Encoding-Zeit vs. Kompressionsrate. Mögliche Werte: ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow. Siehe https://trac.ffmpeg.org/wiki/Encode/H.264.

-size => "$width:$height" (Default: undef)

Breite und Höhe des generierten Video. Ohne Angabe nimmt ffmpeg die Größe der Bilder.

-videoBitrate => $bitrate (Default: 60_000)

Video-Bitrate in kbit/s.

-videoFramerate => $n (Default: 24)

Framerate des Video.

videoToImages() - Extrahiere Bild-Sequenz (Frames) aus Video

Synopsis

    $cmd = $ffm->videoToImages($input,$dir,@opt);

Description

Generiere ein ffmpeg-Kommando, das die Frames aus dem Video $input extrahiert und im Verzeichnis $dir speichert. Die Bilder haben das Format 'jpg'. Der Name der Dateien ist NNNNNN.jpg, von 1 an lückenlos aufsteigend.

Options

-aspectRatio => '16:9'|'4:3' (Default: undef)

Gewünschtes Seitenverhältnis der Bilder. Hat das Video ein abweichendes Seitenverhältnis, wird ein entsprechender Crop-Filter aufgesetzt.

-framestep => $n (Default: 1)

Extrahiere jeden $n-ten Frame.

-pixelFormat=FMT (Default: 'yuvj422p')

Pixel-Format des erzeugten Bildes. Laut Aussage im Netz ist yuvj422p das Standard-Pixel-Format für jpeg-Dateien. Wird das Pixel-Format hier nicht geändert, erzeugt ffmpeg die Bilder in Pixelformat yuvj420p, was Probleme beim Zusammenfügen mit Bildern einer Kamera zu einem Film macht.

-quality => $n (Default: 2)

Qualität der generierten jpg-Bilddateien. Wertebereich: 2-31, mit 2 als bester und 31 als schlechtester Qualität.

-start => $s (Default: 0)

Zeitpunkt in Sekunden (ggf. mit Nachkommastellen) vom Beginn des Video, an dem das Extrahieren der Frames beginnt.

-stop => $s (Default: undef)

Zeitpunkt in Sekunden (ggf. mit Nachkommastellen) vom Beginn des Video, an dem das Extrahieren der Frames endet.

Examples

Ohne Optionen:

    $ffm->videoToImages('video.mp4','img');
    =>
    ffmpeg -y -loglevel error -stats
        -i 'video.mp4'
        -qscale:v 2
        'img/%06d.jpg'

Video-Seitenverhältnis 16:9 zu Bild-Seitenverhältnis 4:3 wandeln:

    $ffm->videoToImages('video.mp4','img',
        -aspectRatio=>'4:3',
    );
    =>
    ffmpeg -y -loglevel error -stats
        -i 'video.mp4'
        -vf 'crop=ih/3*4:ih'
        -qscale:v 2
        'img/%06d.jpg'

Alle Optionen:

    $ffm->videoToImages('video.mp4','img',
        -aspectRatio=>'4:3',
        -framestep=>6,
        -start=>3,
        -stop=>10,
    );
    =>
    ffmpeg -y -loglevel error -stats
        -i 'video.mp4'
        -vf 'framestep=6,crop=ih/3*4:ih'
        -ss 3 -t 7
        -qscale:v 2
        'img/%06d.jpg'

extract() - Extrahiere Abschnitt aus Audio- oder Video-Datei

Synopsis

    $cmd = $class->extract($input,$output,@opt);

Description

Extrahiere von Position $start bis Position $stop einen Teil aus der Audio- oder Video-Datei $input und schreibe ihn auf Datei $output.

Die Extraktion erfolgt ohne Transcoding, also ohne Qualitätsverlust.

Arguments

$input

Eingabe-Datei.

$output

Ausgabe-Datei.

Options

-name => $str (Default: undef)

Füge dem Dateinamen die Bezeichnung $str hinzu.

-play => 0|1|2 (Default: 0)

Extrahiere den Ausschnitt nicht, sondern zeige ihn an. 1=Exit am Ende, 2=Fenster offen lassen (zu erneuten Positionen).

-start => $s (Default: 0)

Start-Position in Sekunden (mit Millisekunden als Nachkommastellen).

-stop => $s (Default: undef)

Ende-Position in Sekunden (mit Millisekunden als Nachkommastellen).

extract169To43() - Extrahiere/Croppe 16:9-Video zu 4:3-Video

Synopsis

    $cmd = $class->extract169To43($input,$output,@opt);

Description

Croppe 16:9-Video $input zum 4:3-Video $output. Die Crop-Operation schneidet links und rechts einen Teil des Video ab.

Arguments

$input

Eingabe-Datei.

$output

Ausgabe-Datei. Wenn undef, wird der Name der Ausgabedatei generiert.

Options

-bitrate => $x (Default: undef)

Die Bitrate des generierten Video in kb/s.

-name => $str (Default: undef)

Füge dem Dateinamen die Bezeichnung $str hinzu.

-play => 0|1|2 (Default: 0)

Zeige das generierte Video im Player an, statt es in einer Datei zu speichern. Bei -play=>2 bleibt das Fenster des Players offen, bis es per Hand geschlossen wird.

-start => $s (Default: 0)

Start-Position in Sekunden (mit Millisekunden als Nachkommastellen).

-stop => $s (Default: undef)

Ende-Position in Sekunden (mit Millisekunden als Nachkommastellen).

-xOffset => $n (Default: undef)

Crop-Offset in x-Richtung. Per Default croppt der crop-Filter mittig.

videoInfo() - Schreibe Video-Stream-Information in XML

Synopsis

    $cmd = $class->videoInfo($input);
    $cmd = $class->videoInfo($input,$streamIndex);

Description

Erzeuge eine ffprobe-Kommandozeile, die Information über den Video-Stream $streamIndex in Datei $input liefert. Ist kein Stream-Index angegeben, wird der erste Stream (Index 0) genommen.

Arguments

$input

Eingabe-Datei.

$streamIndex (Default: 0)

Index des Video-Stream.

Kommando-Ausführung

execute() - Führe FFmpeg-Kommandozeile aus

Synopsis

    $cmd->execute;

Description

Führe FFmpeg-Kommando $cmd aus. Als Ausgabe erscheint lediglich die Fortschrittsanzeige.

VERSION

1.108

AUTHOR

Frank Seitz, http://fseitz.de/

COPYRIGHT

Copyright (C) 2017 Frank Seitz

LICENSE

This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.