The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Prty-1.03
River stage zero No dependents
/ Prty::FFmpeg

NAME

Prty::FFmpeg - 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 Objektmethoden, um eine solche Kommandozeile sukzessive aus Eingabe- und Ausgabe-Dateien, Optionen, Filtern usw. zu konstruieren und andererseits höhere Klassenmethoden, 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

Instanziiere 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

Instanziiere 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-Instanziierung:

    $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);

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.

-framerate => $n (Default: 6)

Anzahl Bilder pro/Sekunde.

-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.

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

Breite und Höhe des generierten Video.

-videoFramerate => $n (Default: 24)

Framerate des Video.

Description

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

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

Synopsis

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

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 Extraghieren der Frames endet.

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.

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);

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).

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.

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

Synopsis

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

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.

Description

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

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

Synopsis

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

Arguments

$input

Eingabe-Datei.

$streamIndex (Default: 0)

Index des Video-Stream.

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.

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.

AUTHOR

Frank Seitz, http://fseitz.de/