• Stars
    star
    1,172
  • Rank 39,881 (Top 0.8 %)
  • Language
    C#
  • License
    Other
  • Created almost 9 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

FFME: The Advanced WPF MediaElement (based on FFmpeg)

FFME: The Advanced WPF MediaElement Alternative

Join the chat at https://gitter.im/ffmediaelement/Lobby Analytics NuGet version NuGet Build status Codacy Badge

⭐ Please star this project if you like it and show your appreciation via PayPal.Me

ffmeplay

Status Updates

  • If you would like to support this project, you can show your appreciation via PayPal.Me
  • Current Status: (2021-06-05) - Release 4.4.350 is now available, (see the Releases)
  • NuGet Package available here: https://www.nuget.org/packages/FFME.Windows/
  • FFmpeg Version: 4.4 -- Make sure you download one built as a SHARED library and for your right architecture (typically x64)
  • BREAKING CHANGE: Starting realease 4.1.320 the Source dependency property has been downgraded to a notification property. Please use the asynchronous Open and Close methods instead.
  • I have been learning a ton while writing this project. You can find my latest video and rendering experiments here (if you are curious)

Please note the current NuGet realease might require a different version of the FFmpeg binaries than the ones of the current state of the source code.

Quick Usage Guide for WPF Apps

Here is a quick guide on how to get started.

  1. Open Visual Studio (v2019 preview recommended), and create a new WPF Application. Target Framework must be 5.0 or above.
  2. Install the NuGet Package from your Package Manager Console: PM> Install-Package FFME.Windows
  3. You need FFmpeg shared binaries (64 or 32 bit, depending on your app's target architecture). Build your own or download a compatible build from FFmpeg Windows Downloads.
  4. Your FFmpeg build should have a bin folder with 3 exe files and some dll files. Copy all those files to a folder such as c:\ffmpeg
  5. Within you application's startup code (Main method), set Unosquare.FFME.Library.FFmpegDirectory = @"c:\ffmpeg";.
  6. Use the FFME MediaElement control as any other WPF control. For example: In your MainForm.xaml, add the namespace: xmlns:ffme="clr-namespace:Unosquare.FFME;assembly=ffme.win" and then add the FFME control your window's XAML: <ffme:MediaElement x:Name="Media" Background="Gray" LoadedBehavior="Play" UnloadedBehavior="Manual" />
  7. To play files or streams, simply call the asynchronous method Open: await Media.Open(new Uri(@"c:\your-file-here"));. Conversely you close the media by calling await Media.Close();

Note: To build your own FFmpeg binaries, I recommend the Media Autobuild Suite but please don't ask for help on it here.

Additional Usage Notes

  • Remember: The Unosquare.FFME.Windows.Sample provides usage examples for plenty of features. Use it as your main reference.
  • The generated API documentation is available here

Features Overview

FFME is an advanced and close drop-in replacement for Microsoft's WPF MediaElement Control. While the standard MediaElement uses DirectX (DirectShow) for media playback, FFME uses FFmpeg to read and decode audio and video. This means that for those of you who want to support stuff like HLS playback, or just don't want to go through the hassle of installing codecs on client machines, using FFME might just be the answer.

FFME provides multiple improvements over the standard MediaElement such as:

  • Fast media seeking and frame-by-frame seeking.
  • Properties such as Position, Balance, SpeedRatio, IsMuted, and Volume are all Dependency Properties.
  • Additional and extended media events. Extracting (and modifying) video, audio and subtitle frames is very easy.
  • Easily apply FFmpeg video and audio filtergraphs.
  • Extract media metadata and specs of a media stream (title, album, bit rate, codecs, FPS, etc).
  • Apply volume, balance and speed ratio to media playback.
  • MediaState actually works on this control. The standard WPF MediaElement is severely lacking in this area.
  • Ability to pick media streams contained in a file or a URL.
  • Specify input and codec parameters.
  • Opt-in hardware decoding acceleration via devices or via codecs.
  • Capture stream packets, audio, video and subtitle frames.
  • Change raw video, audio and subtitle data upon rendering.
  • Perform custom stream reading and stream recording.

... all in a single MediaElement control

FFME also supports opening capture devices. See example URLs below and issue #48

device://dshow/?audio=Microphone (Vengeance 2100):video=MS Webcam 4000
device://gdigrab?title=Command Prompt
device://gdigrab?desktop

If you'd like audio to not change pitch while changing the SpeedRatio property, you'll need the SoundTouch.dll library v2.1.1 available on the same directory as the FFmpeg binaries. You can get the SoundTouch library here.

About how it works

First off, let's review a few concepts. A packet is a group of bytes read from the input. All packets are of a specific MediaType (Audio, Video, Subtitle, Data), and contain some timing information and most importantly compressed data. Packets are sent to a Codec and in turn, the codec produces Frames. Please note that producing 1 frame does not always take exactly 1 packet. A packet may contain many frames but also a frame may require several packets for the decoder to build it. Frames will contain timing informattion and the raw, uncompressed data. Now, you may think you can use frames and show pixels on the screen or send samples to the sound card. We are close, but we still need to do some additional processing. Turns out different Codecs will produce different uncompressed data formats. For example, some video codecs will output pixel data in ARGB, some others in RGB, and some other in YUV420. Therefore, we will need to Convert these frames into something all hardware can use natively. I call these converted frames, MediaBlocks. These MediaBlocks will contain uncompressed data in standard Audio and Video formats that all hardware is able to receive.

The process described above is implemented in 3 different layers:

  • The MediaContainer wraps an input stream. This layer keeps track of a MediaComponentSet which is nothing more than a collecttion of MediaComponent objects. Each MediaComponent holds packet caching, frame decoding, and block conversion logic. It provides the following important functionality:
    • We call Open to open the input stream and detect the different stream components. This also determines the codecs to use.
    • We call Read to read the next available packet and store it in its corresponding component (audio, video, subtitle, data, etc)
    • We call Decode to read the following packet from the queue that each of the components hold, and return a set of frames.
    • Finally, we call Convert to turn a given frame into a MediaBlock.
  • The MediaEngine wraps a MediaContainer and it is responsible for executing commands to control the input stream (Play, Pause, Stop, Seek, etc.) while keeping keeping 3 background workers.
    • The PacketReadingWroker is designed to continuously read packets from the MediaContainer. It will read packets when it needs them and it will pause if it does not need them. This is determined by how much data is in the cache. It will try to keep approximately 1 second of media packets at all times.
    • The FrameDecodingWroker gets the packets that the PacketReadingWorker writes and decodes them into frames. It then converts those frames into blocks and writes them to a MediaBlockBuffer. This block buffer can then be read by something else (the following worker described here) so its contents can be rendered.
    • Finally, the BlockRenderingWorker reads blocks form the MediaBlockBuffers and sends those blocks to a plat-from specific IMediaRenderer.
  • At the highest level, we have a MediaElement. It wraps a MediaEngine and it contains platform-specific implementation of methods to perform stuff like audio rendering, video rendering, subtitle rendering, and property synchronization between the MediaEngine and itself.

A high-level diagram is provided as additional reference below. arch-michelob-2.0

Some Work In Progress

Your help is welcome!

  • I am planning the next version of this control, Floyd. See the Issues section.

Windows: Compiling, Running and Testing

Please note that I am unable to distribute FFmpeg's binaries because I don't know if I am allowed to do so. Follow the instructions below to compile, run and test FFME.

  1. Clone this repository and make sure you have .Net Core 3.1 or above installed.
  2. Download the FFmpeg shared binaries for your target architecture: FFmpeg Windows Downloads.
  3. Extract the contents of the zip file you just downloaded and go to the bin folder that got extracted. You should see 3 exe files and multiple dll files. Select and copy all of them.
  4. Now paste all files from the prior step onto a well-known folder. Take note of the full path. (I used c:\ffmpeg\)
  5. Open the solution and set the Unosquare.FFME.Windows.Sample project as the startup project. You can do this by right clicking on the project and selecting Set as startup project. Please note that you will need Visual Studio 2019 with dotnet 5.0 SDK for your target architecture installed.
  6. Under the Unosquare.FFME.Windows.Sample project, find the file App.xaml.cs and under the constructor, locate the line Library.FFmpegDirectory = @"c:\ffmpeg"; and replace the path so that it points to the folder where you extracted your FFmpeg binaries (dll files).
  7. Click on Start to run the project.
  8. You should see a sample media player. Click on the Open icon located at the bottom right and enter a URL or path to a media file.
  9. The file or URL should play immediately, and all the properties should display to the right of the media display by clicking on the Info icon.
  10. You can use the resulting compiled assemblies in your project without further dependencies. Look for ffme.win.dll.

ffmeplay.exe Sample Application

The source code for this project contains a very capable media player (FFME.Windows.Sample) covering most of the use cases for the FFME control. If you are just checking things out, here is a quick set of shortcut keys that ffmeplay accepts.

Shortcut Key Function Description
G Example of toggling subtitle color
Left Seek 1 frame to the left
Right Seek 1 frame to the right
+ / Volume Up Increase Audio Volume
- / Volume Down Decrease Audio Volume
M / Volume Mute Mute Audio
Up Increase playback Speed
Down Decrease playback speed
A Cycle Through Audio Streams
S Cycle Through Subtitle Streams
Q Cycle Through Video Streams
C Cycle Through Closed Caption Channels
R Reset Changes
Y / H Contrast: Increase / Decrease
U / J Brightness: Increase / Decrease
I / K Saturation: Increase / Decrease
E Example of cycling through audio filters
T Capture Screenshot to desktop/ffplay folder
W Start/Stop recording packets (no transcoding) into a transport stream to desktop/ffplay folder.
Double-click Enter fullscreen
Escape Exit fullscreen
Mouse Wheel Up / Down Zoom: In / Out

Thanks

In no particular order

  • To the FFmpeg team for making the Swiss Army Knife of media. I encourage you to donate to them.
  • To the NAudio team for making the best audio library out there for .NET -- one day I will contribute some improvements I have noticed they need.
  • To Ruslan Balanukhin for his FFmpeg interop bindings generator tool: FFmpeg.AutoGen.
  • To Martin Bohme for his tutorial on creating a video player with FFmpeg.
  • To Barry Mieny for his beautiful FFmpeg logo

Similar Projects

License

  • Please refer to the LICENSE file for more information.

More Repositories

1

embedio

A tiny, cross-platform, module based web server for .NET
C#
1,460
star
2

passcore

A self-service password management tool for Active Directory
C#
1,031
star
3

raspberryio

The Raspberry Pi's IO Functionality in an easy-to-use API for Mono/.NET/C#
C#
673
star
4

swan

Swan stands for Stuff We All Need. Unosquare's collection of C# extension methods and classes.
C#
262
star
5

tubular-react

Material UI table with local or remote data-source. Featuring filtering, sorting, free-text search, export to CSV locally, and aggregations.
TypeScript
205
star
6

sshdeploy

A command-line tool that enables quick build and run deployments over SSH.
C#
141
star
7

wiringpi-dotnet

Provides complete managed access to the popular wiringpi C library
C#
68
star
8

litelib

A cool little wrapper in Entity Framework style for SQLite based on Dapper
C#
63
star
9

pigpio-dotnet

Provides complete managed access to the popular pigpio C library
C
61
star
10

embedio-extras

Additional Modules showing how to extend EmbedIO.
C#
44
star
11

tubular

A set of AngularJS directives designed to rapidly build modern web applications
JavaScript
44
star
12

uno-react

Common functions, HOCs and hooks for React.
TypeScript
28
star
13

swan-aspnetcore

SWAN ASP.NET Core
C#
28
star
14

uno-material-ui

Components and extensions for Material UI
TypeScript
25
star
15

libfprint-cs

The long-awaited C# (.net/mono) wrapper for the great fprint library
C#
20
star
16

best-practices

Unosquare Labs Best Practices
JavaScript
19
star
17

tubular-dotnet

Tubular .NET Library
C#
18
star
18

ffplaydotnet

A port of FFmpeg's FFplay.c
C#
16
star
19

embedio-cli

EmbedIO CLI - .NET Core Global tool
C#
13
star
20

tubular2

Tubular for Angular 7
TypeScript
13
star
21

ef-enterpriseextensions

EntityFramework.EnterpriseExtensions Library
C#
12
star
22

sparkfunfingerprint

SparkFun Fingerprint Reader Interfacing Library for .NET Framework and .NET Core
C#
11
star
23

tenantcore

TenantCore, OWIN multitenancy
C#
10
star
24

wsfingerprint

WaveShare Fingerprint Reader Interfacing Library for .NET
C#
10
star
25

uno-js

Unosquare Typescript/JavaScript Library
TypeScript
10
star
26

tubular-common

Tubular Common Models and Data Transformer
TypeScript
10
star
27

ledemotion

LED Emotion
JavaScript
10
star
28

tubular-aspnet-core-boilerplate

Tubular ASP.NET Core Boilerplate
HTML
8
star
29

tubular-nodejs

Tubular Node.js backend
JavaScript
8
star
30

tubular-boilerplate-csharp

Tubular Boilerplate C#
JavaScript
7
star
31

unosquare.github.io

Main GitHub Pages repository
HTML
7
star
32

pocodata

The no-frills micro ORM for SQL Server
C#
7
star
33

redminetime

A Redmine time entries logger for Windows
C#
6
star
34

entityframework-specification

Unosquare EntityFramework Specification
C#
6
star
35

tubular-boilerplate

Tubular Directives Boilerplate (includes AngularJS and Bootstrap)
HTML
6
star
36

tsrelay

TinySine USB/Wireless Relay Module TOSR1x - Interfacing Library for .NET
C#
5
star
37

unolabs-pi

UnoLabs Raspberry Pi Demo
JavaScript
5
star
38

uno-dashboard-ux

Unosquare Dashboard UX/UI Components
TypeScript
4
star
39

tubular-fabric

Tubular for Office UI Fabric
TypeScript
3
star
40

.github

2
star
41

tubular-react-common

Tubular React Common functions and hooks
TypeScript
2
star
42

eslint-config-unosquare

Eslint Config Unosquare
JavaScript
1
star
43

swan-ldap

SWAN LDAP Client
C#
1
star