ffmprovisr/readme.md

193 lines
9.6 KiB
Markdown
Raw Permalink Normal View History

2016-01-10 16:09:47 +01:00
# [ffmprovisr](http://amiaopensource.github.io/ffmprovisr)
Repository of useful FFmpeg command lines for archivists!
2019-10-07 08:44:37 +02:00
* [What is this?](#what-is-this)
* [How do I see it?](#how-do-i-see-it)
* [How do I contribute?](#how-do-i-contribute)
* [Guidelines for contributing](#guidelines-for-contributing)
2019-10-07 08:44:37 +02:00
* [Code of conduct](#code-of-conduct)
* [Maintainers](#maintainers)
* [Contributors](#contributors)
* [AVHack Team](#avhack-team)
* [Sister projects](#sister-projects)
2019-12-25 10:32:15 +01:00
* [Articles and mentions](#articles-and-mentions)
2019-10-07 08:44:37 +02:00
* [License](#license)
## What is this?
### Project Objective
2017-04-19 10:13:17 +02:00
To facilitate better understanding of FFmpeg through collaborative sharing of useful scripts and detailed flag-level description of how each script works, so archivists can copy-paste and produce their own scripts, but also understand how and why they work.
## How do I see it?
2017-05-17 18:50:29 +02:00
The code is found in the gh-pages branch (the default primary branch). Readme is right here. You can see the site live on [GitHub pages](http://amiaopensource.github.io/ffmprovisr).
2019-02-07 09:38:16 +01:00
You can also install the latest [release](https://github.com/amiaopensource/ffmprovisr/releases) on your computer with the two commands:
2017-05-17 18:50:29 +02:00
```
2019-02-07 09:38:16 +01:00
brew tap amiaopensource/amiaos
brew install ffmprovisr
2017-05-17 18:50:29 +02:00
```
and then call it locally with the command:
```
ffmprovisr
```
2018-12-21 19:55:33 +01:00
This works currently under macOS, Linux and the Linux apps on Windows (Ubuntu and Debian tested). On classic Windows you can install the last [release](https://github.com/amiaopensource/ffmprovisr/releases) manually and the open `index.html` in a browser.
### Parseable list of the commands
2019-03-24 09:39:47 +01:00
A list of all recipes in an easily parseable [ASCII text](recipes.txt) format is provided as well. It contains for each recipe its title and command in the following format:
```
# title of recipe 1
ffmpeg command 1
# title of recipe 2
ffmpeg command 2
...
# title of recipe n-1
ffmpeg command n-1
# title of recipe n
ffmpeg command n
```
2019-03-24 09:40:33 +01:00
The used [one-liner](scripts/get_recipe_list) is in the `scripts` folder.
2019-03-24 09:39:47 +01:00
## How do I contribute?
2017-04-19 09:33:51 +02:00
You are welcome to edit the codebase yourself, or just supply the information and ask it to be added to the site.
### Edit codebase
To contribute to this project directly (and more quickly), clone this repository and create a new branch (`git checkout -b your-branch-name`) and add or modify a new block in `index.html`. Then [submit a pull request](https://github.com/amiaopensource/ffmprovisr/pulls) and the maintainers will review and integrate your code. There is a commented-out sample block available at the bottom of `index.html` that can be a guideline for your command.
#### Guidelines for contributing
* Recipes should ideally do just one thing or solve one problem, to keep things as user-friendly as possible and to avoid unintended side-effects
* Explanations and examples for recipes should be as generic as possible, to allow users to alter the command for their own use-case.
* This may involve the use of `VARIABLE_NAMES`
* Example: [Fade video and audio streams](https://amiaopensource.github.io/ffmprovisr/#fade_streams)
* Some recipes may benefit from including a GIF that shows the output
* Example: [Plays a graphical output showing decibel levels of an input file](https://amiaopensource.github.io/ffmprovisr/#astats)
* Some recipes require an explanatory section which may not fit gracefully into the recipe itself
* Example: [Rewrap a file](https://amiaopensource.github.io/ffmprovisr/#basic-rewrap)
* Recipes involving `-filter_complex` can be some of the most verbose and difficult to understand, so breaking these down as much as possible into their relevant sections is ideal
* Example: [Generate two access MP3s from input](https://amiaopensource.github.io/ffmprovisr/#append_mp3)
2020-06-04 08:39:49 +02:00
* Some recipes may refer to a specific standard or vocabulary, and it's useful to link to these so that the user can scale the recipe to their use case
* Example: [Generate Broadcast WAV](https://amiaopensource.github.io/ffmprovisr/#bwf)
2017-04-19 09:33:51 +02:00
### Make a request
2017-04-19 09:33:51 +02:00
2017-07-14 10:57:41 +02:00
If you are having trouble with coding it yourself or with GitHub, feel free to [submit an issue](https://github.com/amiaopensource/ffmprovisr/issues) with the kind of command you would like to see added to the site.
2017-04-19 09:33:51 +02:00
### General help
2016-07-21 23:40:33 +02:00
If you want to help but don't have a new script to add, you can help us by testing out the scripts available, by refining or clarifying the documentation, or [creating an issue](https://github.com/amiaopensource/ffmprovisr/issues) for anything that sounds confusing and requires clarification.
2016-01-24 16:20:15 +01:00
## Code of Conduct
You can read our contributor code of conduct [here](https://github.com/amiaopensource/ffmprovisr/blob/gh-pages/code_of_conduct.md).
## Maintainers
2018-06-28 20:12:01 +02:00
[Ashley Blewer](https://github.com/ablwr), [Katherine Frances Nagels](https://github.com/kfrn), [Kieran O'Leary](https://github.com/kieranjol) and [Andrew Weaver](https://github.com/privatezero)
## Contributors
* Gathered using [octohatrack](https://github.com/LABHR/octohatrack)
*Code Contributors*:
ablwr (Ashley)
alavigne12 (A. Lavigne)
Anushka-codergirl (Anushka Raj)
bastibeckr (Basti Becker)
bturkus
dericed (Dave Rice)
digitensions (Joanna White)
edsu (Ed Summers)
jamessam (Jim Sam)
jfarbowitz (Jonathan Farbowitz)
kfrn (Katherine Frances Nagels)
kgrons (Kathryn Gronsbell)
kieranjol (Kieran O'Leary)
llogan (Lou Logan)
macasaurusrex (Maura)
mgiraldo (Mauricio Giraldo)
2017-05-22 15:59:43 +02:00
pjotrek-b (Peter B.)
privatezero (Andrew Weaver)
retokromer (Reto Kromer)
rfraimow
All Contributors:
ablwr (Ashley)
alavigne12 (A. Lavigne)
Anushka-codergirl (Anushka Raj)
audiovisualopen
bastibeckr (Basti Becker)
brainwane (Sumana Harihareswara)
2017-05-22 15:59:43 +02:00
bturkus
dericed (Dave Rice)
digitensions (Joanna White)
drodz11 (Dave Rodriguez)
edsu (Ed Summers)
EG-tech (Ethan Gates)
federicomenaquintero (Federico Mena Quintero)
Fizz24
GregH18
2017-05-22 15:59:43 +02:00
jamessam (Jim Sam)
jfarbowitz (Jonathan Farbowitz)
JonnyTech
jronallo (Jason Ronallo)
2017-05-22 15:59:43 +02:00
kellyhaydon (metacynic)
kfrn (Katherine Frances Nagels)
kgrons (Kathryn Gronsbell)
kieranjol (Kieran O'Leary)
llogan (Lou Logan)
macasaurusrex (Maura)
mercuryswitch
mgiraldo (Mauricio Giraldo)
mulvya
nkrabben (Nick Krabbenhoeft)
2017-05-22 15:59:43 +02:00
pjotrek-b (Peter B.)
privatezero (Andrew Weaver)
retokromer (Reto Kromer)
rfraimow
2017-05-22 15:59:43 +02:00
richardpl (Paul B Mahol)
ross-spencer (Ross Spencer)
taschenbach (Tommy Aschenbach)
todrobbins (Tod Robbins)
Repo: amiaopensource/ffmprovisr
GitHub Contributors: 20
All Contributors: 37
Last updated: 2019-12-11
## AVHack Team
[Association of Moving Image Archivists & Digital Library Federation Hack Day 2015](http://wiki.curatecamp.org/index.php/Association_of_Moving_Image_Archivists_%26_Digital_Library_Federation_Hack_Day_2015)
2017-04-19 09:33:51 +02:00
[Ashley Blewer](https://github.com/ablwr), [Eddy Colloton](https://github.com/eddycolloton), Rebecca Dillmeier, [Jonathan Farbowitz](https://github.com/jfarbowitz), [Rebecca Fraimow](https://github.com/rfraimow), Samuel Gutterman, [Kelly Haydon](https://github.com/kellyhaydon), [Reto Kromer](https://github.com/retokromer), Nicole Martin, [Katherine Frances Nagels](https://github.com/kfrn), [Kieran O'Leary](https://github.com/kieranjol), Catriona Schlosser, [Ben Turkus](https://github.com/bturkus)
2016-11-06 22:04:41 +01:00
## Sister projects
[The Cable Bible](https://amiaopensource.github.io/cable-bible/): A Guide to Cables and Connectors Used for Audiovisual Tech
[FFCommand_Engine](https://github.com/ColorlabMD/FFCommand_Engine): a tool for easier use of FFmpeg binaries
2021-01-29 22:24:42 +01:00
[QEMU QED](https://eaasi.gitlab.io/program_docs/qemu-qed/): instructions for using QEMU (Quick EMUlator), a command line application for computer emulation and virtualization
2016-11-07 00:36:32 +01:00
[Script Ahoy](http://dd388.github.io/crals/): Community Resource for Archivists and Librarians Scripting
[sourcecaster](https://datapraxis.github.io/sourcecaster/): helps you use the command line to work through common challenges that come up when working with digital primary sources.
## Articles and mentions
2019-10-08 07:45:58 +02:00
* 2019-09: **Andrew Weaver & Ashley Blewer**, [Sustainability through community: ffmprovisr and the Case for Collaborative Knowledge Transfer](https://ipres2019.org/static/pdf/iPres2019_paper_97.pdf) (PDF), iPRES 2019
2019-10-08 07:43:23 +02:00
- Andrew Weaver [won](https://twitter.com/iPRES2019/status/1177136202144768000) iPres' Best First Time Contribution Award for his work on this paper :)
* 2018-11: ffmprovisr is mentioned in [a job advert](http://web.library.emory.edu/documents/pa_staff_Audiovisual%20Conservator_Nov2018.pdf)!
2019-10-08 07:37:52 +02:00
* 2017-10: **Ashley Blewer & Katherine Nagels**, [ffmprovisr gets a redesign](https://bits.ashleyblewer.com/blog/2017/10/31/ffmprovisr-redesign/)
* 2015-11: **AMIA & DLF Hack Day 2015**, [ffmprovsr](https://wiki.curatecamp.org/index.php/Association_of_Moving_Image_Archivists_&_Digital_Library_Federation_Hack_Day_2015#ffmprovsr) - the genesis of ffmprovisr (then spelled without the 'i')
## License
2017-11-13 15:31:07 +01:00
<a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/80x15.png"></a><br>
This <span xmlns:dct="http://purl.org/dc/terms/" href="http://purl.org/dc/dcmitype/InteractiveResource" rel="dct:type">work</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="http://amiaopensource.github.io/ffmprovisr/" property="cc:attributionName" rel="cc:attributionURL">ffmprovisr</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.<br>
Based on a work at <a xmlns:dct="http://purl.org/dc/terms/" href="https://github.com/amiaopensource/ffmprovisr" rel="dct:source">https://github.com/amiaopensource/ffmprovisr</a>.