syncstart 1.1.1
Calculate the cut needed at start to sync two media files.
License: MIT
Requires Python: >=3.6
Keywords: media file synchronization

=======================================
syncstart(1) Version 1.1.1 \| syncstart
=======================================

SYNOPSIS
========

Command line help::

    usage: syncstart [-h] [--version] [-v] [-b BEGIN] [-t TAKE] [-n] [-d] [-l LOWPASS] [-c] [-s] [-q] in1 in2
    
    CLI interface to sync two media files using their audio or video streams.
      ffmpeg needs to be available.
      
    
    positional arguments:
      in1                   First media file to sync with second.
      in2                   Second media file to sync with first.
    
    options:
      -h, --help            show this help message and exit
      --version             show program's version number and exit
      -v, --video           Compare video streams. (audio is default)
      -b BEGIN, --begin BEGIN
                            Begin comparison X seconds into the inputs. (default: 0)
      -t TAKE, --take TAKE  Take X seconds of the inputs to look at. (default: 20)
      -n, --normalize       Normalizes audio/video values from each stream.
      -d, --denoise         Reduces audio/video noise in each stream.
      -l LOWPASS, --lowpass LOWPASS
                            Audio option: Discards frequencies above the specified Hz, e.g., 300. 0 == off (default)
      -c, --crop            Video option: Crop to 4:3. Helpful when aspect ratios differ.
      -s, --show            Suppress "show diagrams", in case you are confident.
      -q, --quiet           Suppresses standard output except for the CSV result. Output will be:
                            file_to_advance,seconds_to_advance


DESCRIPTION
===========


The steps taken by ``syncstart``:

- get the maximum audio sample frequency or video frame rate among the inputs using ffprobe
- process and extract sample audio/video clips using ffmpeg with some default and optional filters
- read the two clips into a 1D array and apply optional z-score normalization
- compute offset via correlation using scipy ifft/fft
- print ffmpeg/ffprobe output or optionally quiet that
- show diagrams to allow MANUAL correction using ZOOM or optionally suppress that
- print result

MANUAL correction with ZOOM:

- at the checkbox on the top right check or uncheck to make the statement true
- turn on ZOOM with the magnifying glass on the bottom left
- draw a rectangle that stretches between two X that should coincide
  (Y is not relevant but don't make it 0)
- read the final correction from the top right or in the final output

Requirements:

- ffmpeg and ffprobe installed
- Python3 with tk (tk is separate on Ubuntu: python3-tk)

References:

- https://ffmpeg.org/ffmpeg-all.html
- https://dsp.stackexchange.com/questions/736/how-do-i-implement-cross-correlation-to-prove-two-audio-files-are-similar
- https://dsp.stackexchange.com/questions/18846/map-time-difference-between-two-similar-videos

Within Python:

from syncstart import file_offset




INSTALLATION
============

To install for user only, do::

   pip install --user syncstart

Or activate a virtualenv and do::

   pip install syncstart

EXAMPLES
--------

::

  # compute audio offset with default settings:
  syncstart from_s10.m4a from_gopro.m4p

  # compute audio offset using first 10 seconds with denoising, normalization and a 300 Hz lowpass filter:
  syncstart video1.mp4 video2.mkv -t 10 -dnl 300

  # compute video offset using first 20 seconds, don't show plots, only output final result:
  syncstart video1.mp4 video2.mkv -vsq

  # compute video offset using seconds 15 to 25 with denoising, cropping and normalization:
  syncstart video1.mp4 video2.mkv -b 15 -t 10 -vdcn

License
-------

MIT