SFTP Video Player
A Flutter package that enables video playback from SFTP (SSH File Transfer Protocol) files by creating a local HTTP server that streams the content. Built on top of the official video_player package and dartssh2.
Features
- 🎬 Play videos directly from SFTP servers
- 📡 Supports HTTP range requests for video seeking
- 🔧 Extends
VideoPlayerControllerfor compatibility with existing video player widgets - 🎯 Works with Chewie and other video player wrappers
- 🔒 Optional SSL/TLS support for secure streaming
- 📱 Cross-platform support (Android, iOS, desktop)
Why This Package?
When attempting to stream videos from SFTP servers using the default Flutter video_player, I encountered difficulties with direct SFTP protocol support. This package solves that by:
- Creating a local HTTP server
- Streaming SFTP file content through HTTP
- Enabling standard video players to work with SFTP sources
Requirements
Platform-Specific Setup
Android
Add internet permissions to android/app/src/main/AndroidManifest.xml:
<uses-permission android:name="android.permission.INTERNET" />
Allow cleartext traffic in android/app/src/main/AndroidManifest.xml (unless using SSL):
<application
android:usesCleartextTraffic="true"
...>
iOS
Add the following to ios/Runner/Info.plist:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsLocalNetworking</key>
<true/>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
Web
Note: Limited by dartssh2 package's dependency on native sockets, which may not work in all web environments.
Installation
Add this to your package's pubspec.yaml file:
dependencies:
sftp_video_player: ^0.0.1
dartssh2: ^4.1.0
video_player: ^2.4.7
Usage
Basic Example
import 'package:dartssh2/dartssh2.dart';
import 'package:flutter/material.dart';
import 'package:sftp_video_player/sftp_video_player.dart';
import 'package:video_player/video_player.dart';
class VideoPlayerScreen extends StatefulWidget {
@override
_VideoPlayerScreenState createState() => _VideoPlayerScreenState();
}
class _VideoPlayerScreenState extends State<VideoPlayerScreen> {
SftpVideoPlayerController? _controller;
bool _initialized = false;
@override
void initState() {
super.initState();
_initializeVideo();
}
Future<void> _initializeVideo() async {
// Connect to SFTP server
final client = SSHClient(
host: 'your.sftp.server.com',
port: 22,
username: 'your_username',
password: 'your_password',
);
await client.connect();
// Get SFTP file
final sftp = await client.sftp();
final file = sftp.open('/path/to/video.mp4', mode: SftpFileOpenMode.read);
// Create controller
_controller = SftpVideoPlayerController(
file,
videoFormat: StreamVideoFormat.mp4,
serverConfig: VideoServerConfig(
hostname: '127.0.0.1',
port: 8080,
ssl: false,
),
);
// Initialize and play
await _controller!.initialize();
setState(() {
_initialized = true;
});
_controller!.play();
}
@override
void dispose() {
_controller?.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
if (!_initialized) {
return const Center(child: CircularProgressIndicator());
}
return Scaffold(
body: AspectRatio(
aspectRatio: _controller!.value.aspectRatio,
child: VideoPlayer(_controller!),
),
);
}
}
With Chewie
import 'package:chewie/chewie.dart';
// After initializing _controller
final chewieController = ChewieController(
videoPlayerController: _controller,
autoPlay: true,
looping: false,
);
// Use Chewie widget
Chewie(controller: chewieController)
Configuration Options
VideoServerConfig
Configure the local HTTP server:
final serverConfig = VideoServerConfig(
hostname: '127.0.0.1', // Server hostname (default: 127.0.0.1)
port: 8080, // Server port (default: 8080)
ssl: false, // Use HTTPS (default: false)
securityContext: null, // SecurityContext for SSL (required if ssl: true)
);
StreamVideoFormat
Supported video formats:
mp4- MP4 video (most common)webm- WebM videomov- QuickTime MOVmkv- Matroska Videoflv- Flash Videoavi- Custom formats viaStreamVideoFormat.custom()
// Use predefined format
videoFormat: StreamVideoFormat.mp4
// Use custom format
videoFormat: StreamVideoFormat.custom('avi', 'video/x-msvideo')
API Reference
SftpVideoPlayerController
Extends VideoPlayerController to play SFTP files.
Constructor:
SftpVideoPlayerController(
SftpFile file, {
VideoServerConfig serverConfig = const VideoServerConfig(),
StreamVideoFormat? videoFormat,
VideoPlayerOptions? videoPlayerOptions,
String? formatHint,
ClosedCaptionFile? closedCaptionFile,
})
Methods:
initialize()- Initialize the video playerdispose()- Dispose the controller and close the HTTP server
VideoServerConfig
Configuration for the local HTTP server.
Properties:
hostname- Server hostname (default: "127.0.0.1")port- Server port (default: 8080)ssl- Use SSL/TLS (default: false)securityContext- Security context for SSL
Methods:
url()- Returns the complete server URL
StreamVideoFormat
Enumeration of supported video formats.
Static Methods:
custom(String fileExtension, String mimeType)- Create custom formatfrom(String fileExtension)- Get format from file extension
Properties:
mimeType- Returns the MIME type string
Example App
See the example folder for a complete working example. To run it:
- Copy
example/lib/test_conf.dart.exampletoexample/lib/test_conf.dart - Update the SFTP credentials in
test_conf.dart - Run
flutter runin the example directory
Error Handling
The package throws exceptions for common errors:
- Connection failures: SFTP server unreachable or authentication failed
- File not found: The specified video file doesn't exist on the server
- Server binding failed: Port already in use or binding error
- Initialization failed: Video format not supported or corrupted file
Always wrap initialization in try-catch:
try {
await _controller!.initialize();
} catch (e) {
print('Failed to initialize video: $e');
// Handle error
}
Troubleshooting
Video won't play
- Ensure the video file exists on the SFTP server
- Check that the video format is supported
- Verify the video file is not corrupted
Connection errors
- Verify SFTP server credentials
- Check network connectivity
- Ensure the server allows SFTP connections
Port already in use
- Change the port in
VideoServerConfig - Close other applications using the port
License
See the LICENSE file for details.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Credits
Built with: