/ 
Quiq-1.222
River stage zero No dependents
/ Quiq::FFmpeg

NAME

Quiq::FFmpeg - Konstruiere eine FFmpeg-Kommandozeile

BASE CLASS

Quiq::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;
$cmd = $class->new($str);

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 Quiq::File-Objekt und liefere dieses zurück. Das Objekt wird gecached.

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

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.

-videoFilter => $filter

Optionale Filterangabe. Z.B. -videoFilter => 'lutyuv=y=val*1.4,hue=s=10'

-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 Extrahieren 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 einem Format, das die Klasse Quiq::Duration akzeptiert.

-stop => $s (Default: undef)

Ende-Position in einem Format, das die Klasse Quiq::Duration akzeptiert.

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.

VERSION

1.222

AUTHOR

Frank Seitz, http://fseitz.de/

COPYRIGHT

Copyright (C) 2024 Frank Seitz

LICENSE

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