-- vidspinner --

vidspinner is a Python library for easily creating unique versions of videos using filters, text, and audio effects.

📥 Installation

pip install vidspinner

💡 Quick Start

from vidspinner import MontageBuilder
from vidspinner.filters import Filter
from vidspinner.builders.text import TextBuilder, TextEffectBuilder
from vidspinner.builders.audio import AudioBuilder

mb = MontageBuilder()

mb.input = 'input.mp4'
mb.output = 'output.mp4'
mb.clear_meta_tags = True # clear meta tags

mb.add_filter(Filter.RETRO)

########### Test text ############ 
tb = TextBuilder()
tb.set_params(text='Wow! It is a simple text!')
mb.add_filter(tb.build(), start_duration=2, end_duration=5) # add text
##################################

####################### Fisheye effect ################
mb.add_filter(Filter.FISHEYE, start_duration=3, end_duration=5.8)
########################################################


############## Creating logo ###########
tb.set_font('comic_sans.ttf')
tb.set_params(color='cyan', text='VidSpinner', size=48)

teb = TextEffectBuilder()
teb.add_effect(effect='SHADOW', x=5, y=5, color='black')
teb.add_effect(effect='SHAKE', x=0, y=1850, amplitude=6) # for the shake effect you need to set the position of the text relative to its current coordinates.

box_effect = 'box=1:boxcolor={color}@{transparency}:boxborderw={width}' # custom text effect

teb.add_custom_effect(box_effect.format(
  color='lime',
  transparency=0.3,
  width=3
))

tb.add_effect(teb)

mb.add_filter(tb.build())
#######################################

########### Audio manipulations ############
ab = AudioBuilder()
ab.set_pitch(1.5)
mb.set_audio(ab)
#####################################

mb.build() # build result

🎥 Example (Quickstart Result):

📹 Input:

input.mp4

🔮 Output:

output.mp4

🎨 Features

• 16 built-in filters like retro, black & white, psychedelic etc.
• Add custom text with control over font, size, position
• Animate text with scroll, shake, blink and more
• Trim, pitch shift, speed up/slow down audio
• Clear metadata to avoid detection

🧰 Built-in Filters

from vidspinner.filters import Filter

print(Filter.get_filters()) # to see all filters 

🎨 Working with Filters

Add a filter:

mb = MontageBuilder()
mb.add_filter(Filter.RETRO) # add filter
mb.add_filter(Filter.VIGNETTE) # add several filters

Add a custom filter:

mb.add_filter('rotate=PI/4') 

🖌️ Working with Text

Add text:

from vidspinner.builders.text import TextBuilder

tb = TextBuilder()
tb.set_params(
  text='Hello World!',
  position='CENTER' 
)
text = tb.build()
mb.add_filter(text)

Stylize text and custom position:

from vidspinner.builders.text import TextBuilder

tb = TextBuilder()
tb.set_font('comic_sans.ttf')
tb.set_params(
  position='COORDS',
  text='Hello World', 
  color='blue',
  size=32,
  x=0,
  y=0
)
text = tb.build()
mb.add_filter(text)

Some text positions:

'CENTER' - Center text horizontally and vertically
'CENTER_RIGHT' - Center vertically, align right
'CENTER_LEFT' - Center vertically, align left

'BOTTOM' - Align text to bottom center  
'BOTTOM_LEFT' - Align text to bottom left
'BOTTOM_RIGHT' - Align text to bottom right
'BOTTOM_CENTER' - Align text to bottom center

'TOP' - Align text to top center
'TOP_RIGHT' - Align text to top right
'TOP_LEFT' - Align text to top left 
'TOP_CENTER' - Align text to top center

'COORDS' - Specify x and y coordinates

Add text with effects:

from vidspinner.builders.text import TextBuilder, TextEffectBuilder

tb = TextBuilder()

te = TextEffectBuilder()
te.add_effect('BLINK', interval=3)
te.add_effect('SHADOW', color='gray', x=5, y=5)

tb.set_params(
  text='Hello World!'
)

tb.add_effect(te) 

text = tb.build()

mb.add_filter(text)

Some text effects:

'BLINK' - Text blinks
'SHADOW' - Text shadow
'SHAKE' - Shake text randomly
'SCROLL_TB' - Scroll text top to bottom 
'SCROLL_LR' - Scroll text left to right
'FADE_IN' - Fade in text over duration
'FADE_OUT' - Fade out text over duration

Some common effect parameters:

• BLINK - interval
• SHADOW - color, x, y
• SHAKE - amplitude, x, y
• FADE_IN - duration
• FADE_OUT - duration
• SCROLL_TB - duration
• SCROLL_LR - duration

🎙️ Working with Audio

Change audio track:

from vidspinner.builders.audio import AudioBuilder

ab = AudioBuilder()
ab.set_audiotrack('track.mp3', start_time=10, end_time=20)
mb.set_audio(ab)

Change volume:

ab.set_volume(0.5)

Pitch shift:

ab.set_pitch(1.5)

🗑️ Clearing Metadata

To clear metadata tags and avoid detection:

mb.clear_meta_tags = True 

This will add the -map_metadata -1 flag to ffmpeg to clear metadata tags like title, author, etc.

📄 License

VidSpinner is MIT licensed.