Package: python-ffmpeg-video-streaming
ðŸ“¼ Python FFmpeg Video StreamingOverviewThis package uses theFFmpegto package media content for online streaming such as DASH and HLS. You can also useDRMfor HLS packaging. There are several options to open a file from a cloud and save files to clouds as well.Full Documentationis available describing all features and components.In this version(>=v0.1.0) all codes are rewritten from scratch. If you find any bugs in the library, pleasefile an issue.Pull requestsare also welcome.ContentsRequirementsInstallationQuickstartOpening a ResourceDASHHLSEncryption(DRM)TranscodingSaving FilesMetadataConversionSeveral Open Source PlayersFAQsContributing and Reporting BugsCreditsLicenseRequirementsThis version of the package is only compatible withPython 3.8or higher.To use this package, you need toinstall the FFmpeg. You will need both FFmpeg and FFProbe binaries to use it.InstallationInstall the package viapip:pipinstallpython-ffmpeg-video-streamingAlternatively, add the dependency directly to yourrequirements.txtfile:python-ffmpeg-video-streaming>=0.1QuickstartFirst of all, you need to import the package in your code:importffmpeg_streamingOpening a ResourceThere are several ways to open a resource.1. From an FFmpeg supported resourceYou can pass a local path of video(or a supported resource) to theinputmethod:video=ffmpeg_streaming.input('/var/media/video.mp4')SeeFFmpeg Protocols Documentationfor more information about supported resources such as HTTP, FTP, and etc.For example:video=ffmpeg_streaming.input('https://www.aminyazdanpanah.com/?"PATH TO A VIDEO FILE" or "PATH TO A LIVE HTTP STREAM"')2. From CloudsYou can open a file from a cloud by passing an instance of the Cloud object to theinputmethod.fromffmpeg_streamingimportS3s3=S3(aws_access_key_id='YOUR_KEY_ID',aws_secret_access_key='YOUR_KEY_SECRET',region_name='YOUR_REGION')video=ffmpeg_streaming.input(s3,bucket_name="bucket-name",key="video.mp4")Visitthis pageto see some examples of opening a file fromAmazon S3,Google Cloud Storage,Microsoft Azure Storage, and a custom cloud.3. Capture Webcam or Screen (Live Streaming)You can pass the name of a supported, connected capture device(i.e. the name of a webcam, camera, screen and etc) to theinputmethod to stream a live media over the network from your connected device.capture=ffmpeg_streaming.input('CAMERA NAME OR SCREEN NAME',capture=True)To list the supported, connected capture devices, seeFFmpeg Capture WebcamandFFmpeg Capture Desktop.DASHDynamic Adaptive Streaming over HTTP (DASH), also known as MPEG-DASH, is an adaptive bitrate streaming technique that enables high-quality streaming of media content over the Internet delivered from conventional HTTP web servers.Learn moreCreate DASH files:fromffmpeg_streamingimportFormatsdash=video.dash(Formats.h264())dash.auto_generate_representations()dash.output('/var/media/dash.mpd')Generate representations manually:fromffmpeg_streamingimportFormats,Bitrate,Representation,Size_144p=Representation(Size(256,144),Bitrate(95*1024,64*1024))_240p=Representation(Size(426,240),Bitrate(150*1024,94*1024))_360p=Representation(Size(640,360),Bitrate(276*1024,128*1024))_480p=Representation(Size(854,480),Bitrate(750*1024,192*1024))_720p=Representation(Size(1280,720),Bitrate(2048*1024,320*1024))_1080p=Representation(Size(1920,1080),Bitrate(4096*1024,320*1024))_2k=Representation(Size(2560,1440),Bitrate(6144*1024,320*1024))_4k=Representation(Size(3840,2160),Bitrate(17408*1024,320*1024))dash=video.dash(Formats.h264())dash.representations(_144p,_240p,_360p,_480p,_720p,_1080p,_2k,_4k)dash.output('/var/media/dash.mpd')SeeDASH sectionin the documentation, for more examples.HLSHTTP Live Streaming (also known as HLS)is an HTTP-based adaptive bitrate streaming communications protocol implemented by Apple Inc. as part of its QuickTime, Safari, OS X, and iOS software. Client implementations are also available in Microsoft Edge, Firefox, and some versions of Google Chrome. Support is widespread in streaming media servers.Learn moreCreate HLS files:fromffmpeg_streamingimportFormatshls=video.hls(Formats.h264())hls.auto_generate_representations()hls.output('/var/media/hls.m3u8')Generate representations manually:fromffmpeg_streamingimportFormats,Bitrate,Representation,Size_360p=Representation(Size(640,360),Bitrate(276*1024,128*1024))_480p=Representation(Size(854,480),Bitrate(750*1024,192*1024))_720p=Representation(Size(1280,720),Bitrate(2048*1024,320*1024))hls=video.hls(Formats.h264())hls.representations(_360p,_480p,_720p)hls.output('/var/media/hls.m3u8')SeeHLS sectionin the documentation, for more examples such as Fragmented MP4, live from camera/screen and so on.Encryption(DRM)The encryption process requires some kind of secret (key) together with an encryption algorithm. HLS uses AES in cipher block chaining (CBC) mode. This means each block is encrypted using the ciphertext of the preceding block.Learn moreYou must specify a path to save a random key to your local machine and also a URL(or a path) to access the key on your website(the key you will save must be accessible from your website). You must pass both these parameters to theencryptionmethod:Single KeyThe following code generates a key for all segment files.fromffmpeg_streamingimportFormats#A path you want to save a random key to your local machinesave_to='/home/public_html/"PATH TO THE KEY DIRECTORY"/key'#A URL (or a path) to access the key on your websiteurl='https://www.aminyazdanpanah.com/?"PATH TO THE KEY DIRECTORY"/key'# or url = '/"PATH TO THE KEY DIRECTORY"/key';hls=video.hls(Formats.h264())hls.encryption(save_to,url)hls.auto_generate_representations()hls.output('/var/media/hls.m3u8')Key RotationAn integer as a "key rotation period" can also be passed to theencryptionmethod (i.e.encryption(save_to, url, 10)) to use a different key for each set of segments, rotating to a new key after this many segments. For example, if 10 segment files have been generated then it will generate a new key. If you set this value to1, each segment file will be encrypted with a new encryption key. This can improve security and allows for more flexibility.Seethe examplefor more information.IMPORTANT:It is very important to protect your key(s) on your website. For example, you can use a token(using a Get/Post HTTP method or add a token to authorization header) to check if the user is eligible to access the key or not. You can also use a session(or cookie) on your website to restrict access to the key(s)(It is highly recommended).DRMHowever FFmpeg supports AES encryption for HLS packaging, which you can encrypt your content, it is not a fullDRMsolution. If you want to use a full DRM solution, I recommend tryingFairPlay Streamingsolution which then securely exchange keys, and protect playback on devices.BesidesApple's FairPlayDRM system, you can also use other DRM systems such asMicrosoft's PlayReadyandGoogle's Widevine.TranscodingYou can get realtime information about the transcoding using the following code.fromffmpeg_streamingimportFormatsimportsysdefmonitor(ffmpeg,duration,time_,time_left,process):"""Handling proccess.Examples:1. Logging or printing ffmpeg commandlogging.info(ffmpeg) or print(ffmpeg)2. Handling Process objectif "something happened":process.terminate()3. Email someone to inform about the time of finishing processif time_left > 3600 and not already_send:  # if it takes more than one hour and you have not emailed them alreadyready_time = time_left + time.time()Email.send(email='someone@somedomain.com',subject='Your video will be ready by %s' % datetime.timedelta(seconds=ready_time),message='Your video takes more than %s hour(s) ...' % round(time_left / 3600))already_send = True4. Create a socket connection and show a progress bar(or other parameters) to your usersSocket.broadcast(address=127.0.0.1port=5050data={percentage = per,time_left = datetime.timedelta(seconds=int(time_left))}):param ffmpeg: ffmpeg command line:param duration: duration of the video:param time_: current time of transcoded video:param time_left: seconds left to finish the video process:param process: subprocess object:return: None"""per=round(time_/duration*100)sys.stdout.write("\rTranscoding...(%s%%)%sleft [%s%s]"%(per,datetime.timedelta(seconds=int(time_left)),'#'*per,'-'*(100-per)))sys.stdout.flush()hls=video.hls(Formats.h264())hls.auto_generate_representations()hls.output('/var/media/hls.m3u8',monitor=monitor)Output From a Terminal:Saving FilesThere are several ways to save files.1. To a Local PathYou can pass a local path to theoutputmethod. If there is no directory, then the package will create it.fromffmpeg_streamingimportFormatsdash=video.dash(Formats.h264())dash.auto_generate_representations()dash.output('/var/media/dash.mpd')It can also be None. The default path to save files is the input directory.fromffmpeg_streamingimportFormatshls=video.hls(Formats.h264())hls.auto_generate_representations()hls.output()NOTE:If you open a file from a cloud and do not pass a path to save the file to your local machine, you will have to pass a local path to theoutputmethod.2. To CloudsYou can save your files to a cloud by passing an instance of aCloudManagerto theoutputmethod.fromffmpeg_streamingimportS3,CloudManagers3=S3(aws_access_key_id='YOUR_KEY_ID',aws_secret_access_key='YOUR_KEY_SECRET',region_name='YOUR_REGION')save_to_s3=CloudManager().add(s3,bucket_name="bucket-name")hls.output(clouds=save_to_s3)A path can also be passed to save a copy of files to your local machine.hls.output('/var/media/hls.m3u8',clouds=save_to_s3)Visitthis pageto see some examples of saving files toAmazon S3,Google Cloud Storage,Microsoft Azure Storage, and a custom cloud.NOTE:This option is only valid forVOD(it does not support live streaming).Schema:The relation isone-to-many3. To a Server InstantlyYou can pass a URL(or a supported resource likeFTP) to theoutputmethod to upload all the segments files to the HTTP server(or other protocols) using the HTTP PUT method and update the manifest files every refresh times.# DASHdash.output('http://YOUR-WEBSITE.COM/live-stream/out.mpd')# HLShls.save_master_playlist('/var/media/hls.m3u8')#Before running the following code, you should upload the master playlist to the server. For example upload the '/var/media/hls.m3u8' to 'ftp://[user[:password]@]server[:port]/var/media/hls.m3u8'hls.output('ftp://[user[:password]@]server[:port]/var/media/hls.m3u8')SeeFFmpeg Protocols Documentationfor more information about supported resources.MetadataYou can get information from the video file using the following code.fromffmpeg_streamingimportFFProbeffprobe=FFProbe('/var/media/video.mp4')Seethe examplefor more information.ConversionYou can convert your stream to a file or to another stream protocol. You should pass a manifest of the stream to theinputmethod:1. HLS To DASHfromffmpeg_streamingimportFormats,Bitrate,Representation,Sizevideo=ffmpeg_streaming.input('https://www.aminyazdanpanah.com/?PATH/TO/HLS-MANIFEST.M3U8')_480p=Representation(Size(854,480),Bitrate(750*1024,192*1024))dash=video.dash(Formats.h264())dash.representations(_480p)dash.output('/var/media/dash.mpd')2. DASH To HLSvideo=ffmpeg_streaming.input('https://www.aminyazdanpanah.com/?PATH/TO/DASH-MANIFEST.MPD')hls=video.hls(Formats.h264())hls.auto_generate_representations()hls.output('/var/media/hls.m3u8')3. Stream(DASH or HLS) To Filevideo=ffmpeg_streaming.input('https://www.aminyazdanpanah.com/?PATH/TO/MANIFEST.MPD or M3U8')stream=video.stream2file(Formats.h264())stream.output('/var/media/new-video.mp4')Several Open Source PlayersYou can use these libraries to play your streams.WEBDASH and HLS:Video.js 7(Recommended) -videojs-http-streaming (VHS)PlyrDPlayerMediaElement.jsClapprShaka PlayerFlowplayerDASH:dash.jsHLS:hls.jsAndroidDASH and HLS:ExoPlayer(Recommended)VLC for AndroidIOSDASH:MPEGDASH-iOS-PlayerHLS:PlayerAndroid and IOSDASH and HLS:ijkplayerWindows, Linux, and macOSDASH and HLS:FFmpeg(ffplay)(Recommended)VLC media playerFAQsI created stream files and now what should I pass to a player?You must pass amaster playlist(manifest) URL(e.x.https://www.aminyazdanpanah.com/?"PATH TO STREAM DIRECTORY"/dash-stream.mpdor/PATH_TO_STREAM_DIRECTORY/hls-stream.m3u8) to a player.
See the demo page of these players for more information(hls.js Demo,dash.js Demo,videojs Demoand etc).My player does not show the quality selector button to change the video quality?Some Players do not have an embedded quality selector button to change this option and you should install(or add) the plugin for this use case. For example, if you are using Videojs to play your stream, you can installvideojs-hls-quality-selectorto show the quality selector. For adding a plugin to other players, you can easily Google it!I uploaded my stream files to a cloud but it does not play on my website?If you save your stream content to a cloud(i.e.Amazon S3), make sure your contents arePUBLIC. If they are not, you must change the access control.DoesIOSsupport the DASH stream?No, IOS does not have native support for DASH. Although there are some libraries such asViblastandMPEGDASH-iOS-Playerto support this technique, I have never tested them. So maybe some of them will not work properly.Seethis pagefor more FAQs.Contributing and Reporting BugsI'd love your help in improving, correcting, adding to the specification. Pleasefile an issueorsubmit a pull request.SeeContributing Filefor more information.If you discover a security vulnerability within this package, please seeSECURITY Filefor more information.CreditsAmin YazdanpanahAll ContributorsLicenseThe MIT License (MIT). SeeLicense Filefor more information.