Renderer

Table of Contents

• Setup
• Running render
• Contributing
  • Formatting
  • Testing
  • Quick Start
  • My Setup
  • Write to the CHANGELOG
• Building
  • Testing the Build
  • The JumpCutter Format
• Known Bugs
  • Mac Failure
  • FFmpeg
• Grievances
  • Accessibility
  • Examples Submodule
  • Classes
  • Layering
  • Pass Through
  • Video Toolbox
• Running the README
• Suggested Reads

Setup

Note

python3.8

Caution

You need a local build of ffmpeg>=4.3.[1]

Be sure to grab the submodules for this project.

git submodule init
git submodule update

Or with the --recurse-submodule flag when you clone.

Our submodules hold a shared folder of test files.

pip install -r requirements.txt

Want a better README?

See the Running the README or Suggested Reads

Running render

Just as the binary would run:

python render.py <cuts.json>

I suggest this setup to run this with pytest.

Our renderer currently needs an input JSON file.^[2]

Contributing

Note	visible tests displaying your changes lead to faster pull requests.

Please install pytest and continue to test your changes with pytest.

Formatting

Probably the biggest requirement for pull requests

For quick setup see Quick Start. (This is all a part of the vim setup)

For linting you should follow: - autopep8 - flake8 - pylint

Testing

Standard pytest.

We hope to rely on pytest for pr testing.

Warning

Always use the ffmpeg mark! This is necessary because our ci deployment skips all tests that require ffmpeg.

We have included a test video and JSON file in the submodule.

See The JumpCutter Format to replicate our JSON input.

Quick Start

virutalenv and pytest is best

python3 -m pip install virtualenv
virtualenv -p python3.8 venv
source venv/bin/activate
pip install -r requirements.txt
pip install autopep8 pytest flake8 pylint rope

My Setup

Because I love our devs, here’s the best way to test your changes

Install python-mode for vim with coc-python. Together these will, autopep8, flake8, pyline, and rope.

You can then split your terminals:

Terminal 1

vim render.py

For editing.

Terminal 2

nodemon -e "py,json" -x "pytest -s -m render"

For testing.

Terminal 3

less +F logs/render.log

For reading the log live.

Write to the CHANGELOG

asdf

CHANGELOG

You don’t need to go in depth, CHANGELOG is mostly so we can stay ahead of changes and squash bugs that arise with updates.

This is also necessary if you want your version to go live.

Change Log Formatting

You understand basic markdown, but some things to remember

• New versions go at the top of the file

• Considering not every commit is a new version, add your changes to the bottom of the current version header

• When talking about a file feel free to include a link to it

In case you were wondering, I’ve pretty much ripped off Angular’s format for CHANGELOG.

Change Log Headers

This is not exclusive, but if you use another header, you should add it here so we can continue to use it.

Changes

You added some new code.

UI Improvements

You changed the layout, style, appearance, or functionally.

Performance Improvements

You just changed the functionality of something so it runs smoother.

General Improvements

You can’t think of a better place to put your changes.

• Some changes that only effect the local build.

• Changes to the start script or similar.

Bug Fixes

You fixed some broken code.

BREAKING CHANGES

Your change will break something else.

• This should be the last header

• Generally this should detail a change you’ve mentioned under another header.

• Make it easier by using the same bullet as the change.

DEPRECATIONS

Use this with the @depricated JSDoc tag

Pydoc doesn’t have this but I hear deprecation is good?

Building

This is the best part!

To run the build on any system you can simply execute local_run

Note	We use pyinstaller==4.0 becuase of major a security battle between Windows and python.

This will essentially run pyinstaller render.spec.

This is the final binary we use. Please be sure to test that this builds.

Warning

Changing the requirements.txt or this spec file can lead to unnecessary stress.

Testing the Build

You can run this live!

Steps

• You need to open JumpCutter FIRST

• this unpacks its current render into it’s bin fodder

• local_run.sh

• copy the render script over

• make sure to make this executable

• this is chmod except on windows where you rename it render.exe

The JumpCutter Format

Since this is proprietary, here is a simple example of our json.

{
    "frameRate": 30,
    "outFile": "layered.mp4",
    "resolution": null,
    "layers": [
        [
            {
                "timelineStart": 35000,
                "sourceFile": "uploadTest2.mp4",
                "opType": "jumpcutter",
                "speed": {
                    "sounded": 0.9,
                    "silent": null
                },
                "cuts": [
                    {
                        "start": 0.333,
                        "end": 1.6
                    },
                    {
                        "start": 3.4,
                        "end": 4.7
                    },
                    {
                        "start": 6.467,
                        "end": 7.667
                    },
                    {
                        "start": 10.433,
                        "end": 11.7
                    },
                    {
                        "start": 13.9,
                        "end": 14.233
                    },
                    {
                        "start": 14.233,
                        "end": 14.233
                    }
                ]
            }
        ],
        [
            {
                "timelineStart": 0,
                "sourceFile": "background.mp4",
                "opType": "asdf"
            }
        ]
    ]
}

Known Bugs

Maybe we can delete this section

For my OpenSource people: we can eventually move this to Issues

Mac Failure

This is a rather recent issue…​

FFmpeg

Our packaged binary does not support the nvidia encoder on linux. It seemingly just isn’t included.

Grievances

A section to list the major TODOs

For the OpenSource community see Accessibility

Pass Through is another super useful section.

Accessibility

Our current renderer runs in a quasi CLI with our own JSON format.

Input Parameters Should Come From The Socket

Since our local app supports sockets, we should expand on this interaction to include input data from the socket.

Examples Submodule

While we -can- make our inputs more open in nature…​

We need our examples repo to include what we need to easily reproduce tests.

PLEASE Contact me to get an output json

This is a temporary measure to fill up JC-examples for everyone else

Note	this is not necessary, considering you can grab this json from your tmp files

Classes

It’s all chonked into a huge file that isn’t DRY at all.

The render is currently a single class with class-wide variable that are relative to the last run of ffprobe.

An example solution would be a Video class that inputall all the ffprobe actions.

Layering

You might have noticed the input array is two dimensional.

Feel free to build out the layering. It hasn’t been tested since laying was removed from the JumpCutter app.

Pass Through

This is the biggest potential performance improvement.

You might notice this:

if self.bit_rate is not None:
    kwargs['b'] = self.bit_rate
    kwargs['maxrate'] = self.bit_rate
    kwargs['bufsize'] = 2 * self.bit_rate
kwargs['profile'] = 'high'
kwargs['preset'] = 'slow'

This is to fix a mac issue.

On Mac, mov files would lose their quality and introduce artifacts; now we set the preset and profile.

With mp4 (to begin with) ffmpeg should be able to pass through the codec and apply cuts without rencoding. There is a significant speed increase to be gained here, this is just difficult with obscure video wrappers and less common encoders.

Video Toolbox

The tool to make mac faster makes it slower.

This introduces artifacting with no increase in speed. Please help.

Running the README

A simple way to run with the features of asciidoc.

For this you need to get ruby installed - I suggest RVM for that.

Assuming you have ruby, run:

bundle install
guard start

Suggested Reads

This section is a placeholder.

---

1. ffmpeg 4.3 is not a current/stable release

2. "We hope to introduce a websocket input method \n see [open-interaction]"