Skip to content

Commit 5ddcfde

Browse files
iman-zamaniiman-zamani
authored
Revise README for clarity and updated information
Updated README to clarify features, usage, and installation instructions.
1 parent 3035971 commit 5ddcfde

File tree

1 file changed

+57
-96
lines changed

1 file changed

+57
-96
lines changed

‎README.md‎

Lines changed: 57 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -2,131 +2,92 @@
22
<img src="Assets/seamless_logo.png" width="300" alt="Seamless App Icon">
33
</p>
44

5-
# Seamless
6-
7-
8-
Seamless is a straightforward, open-source file transfer utility designed to solve the common problem of sending files instantly between different operating systems on a local network.
9-
10-
It is built for users and developers who prefer a simple, cable-free alternative to moving files between mobile and desktop platforms.
11-
12-
---
13-
14-
## Downloads & Pre-built Releases
15-
16-
Pre-built application binaries are available for common platforms, allowing you to use Seamless without needing to clone the repository or run scripts:
17-
18-
* **Android:** Download the `.apk` file from the [Releases page](https://github.com/iman-zamani/seamless/releases).
19-
* **macOS:** Download the pre-built application bundle from the [Releases page](https://github.com/iman-zamani/seamless/releases).
20-
* **Windows / Linux:** Requires Python and manual setup (see "Getting Started" below).
21-
22-
---
235

24-
## Key Features
25-
26-
* **Cross-Platform File Transfer:** Seamlessly share files between **Android, macOS, Windows, and Linux** using your local Wi-Fi network.
27-
* **Zero-Configuration Discovery:** Devices automatically locate each other using UDP broadcasting on the local subnet. No manual IP configuration is required.
28-
* **High-Speed Transfers:** Utilizes raw TCP sockets with optimized 64KB buffer sizes, ensuring stable and fast transfers limited only by your router speed.
29-
* **Modern UI:** Features a native-feeling dark-mode GUI using `CustomTkinter` on desktop and Material Design on Android.
30-
31-
---
32-
33-
## Tech Stack
34-
35-
### Desktop (Windows / macOS / Linux)
36-
37-
| Component | Technology | Details |
38-
| :--- | :--- | :--- |
39-
| **Language** | Python 3.x | |
40-
| **GUI Framework** | [CustomTkinter](https://github.com/TomSchimansky/CustomTkinter) | For a modern, dark-mode native look. |
41-
| **Networking** | Native `socket` & `threading` | Used for asynchronous discovery and file streaming. |
6+
# Seamless
427

43-
### Mobile (Android)
8+
Seamless is an open-source utility for transferring files between Android, macOS, Windows, and Linux over a local network. It uses UDP for device discovery and TCP for file transmission without requiring external servers or internet access.
449

45-
| Component | Technology | Details |
46-
| :--- | :--- | :--- |
47-
| **Language** | Kotlin | Targeting Android 7.0 (Nougat) and higher. |
48-
| **Concurrency** | Kotlin Coroutines (`Dispatchers.IO`) | For non-blocking network operations. |
49-
| **Networking** | `java.net.Socket` / `DatagramPacket` | TCP for streaming, UDP for discovery. |
10+
-----
5011

51-
---
12+
## Downloads
5213

53-
## Getting Started (For Developers)
14+
Binaries are available for Android and macOS. Windows and Linux users must run from source.
5415

55-
### Prerequisites
16+
| Platform | Installation Method |
17+
| :--- | :--- |
18+
| **Android** | [Download .apk (Releases)](https://github.com/iman-zamani/seamless/releases) |
19+
| **macOS** | [Download App Bundle (Releases)](https://github.com/iman-zamani/seamless/releases) |
20+
| **Win / Linux** | Run from source (see *Development Setup* below) |
5621

57-
* **Desktop:** Python 3.8 or higher.
58-
* **Android:** Android 7.0 (Nougat) or higher.
59-
* **Network:** Both devices must be connected to the **same local Wi-Fi network**.
22+
-----
6023

61-
### 1\. Running the Desktop Client
24+
## Usage
6225

63-
The desktop application is located in the root of the repository as `seamless.py`.
26+
**Note:** The receiver must be in "Receive" mode before the sender begins scanning.
6427

65-
1. **Clone the repository:**
66-
```bash
67-
git clone https://github.com/iman-zamani/seamless.git
68-
cd seamless
69-
```
28+
1. **Network:** Connect both devices to the same Wi-Fi network.
29+
2. **Receiver:** Open the application and select **Receive Files**.
30+
3. **Sender:**
31+
* Open the application and select **Send Files**.
32+
* Select the file(s) to transfer.
33+
* Click **Scan Network**.
34+
* Select the target device from the list to initiate transfer.
7035

71-
2. **Install dependencies (requires `customtkinter`):**
72-
```bash
73-
pip install customtkinter
74-
```
36+
-----
7537

76-
3. **Run the application:**
77-
```bash
78-
python seamless.py
79-
```
38+
## Features
8039

81-
### 2\. Running the Android App
40+
* **Local Network Only:** Transfers occur strictly over LAN; no data leaves the local subnet.
41+
* **Discovery:** Uses UDP broadcasting to locate devices without manual IP entry.
42+
* **Transport:** Uses raw TCP sockets with 64KB buffers for data streaming.
43+
* **Cross-Platform:** Python/CustomTkinter (Desktop) and Kotlin (Android) clients are fully interoperable.
8244

83-
1. Open the `Android/` folder in **Android Studio**.
84-
2. Sync Gradle files, connect your device or start an emulator.
85-
3. Click **Run** in Android Studio.
86-
4. *Note: Ensure **Storage permissions** are granted upon the first launch on the Android device.*
45+
-----
8746

88-
---
47+
## Troubleshooting
8948

90-
## Usage Guide (Send & Receive)
49+
If connection fails, verify the following:
9150

92-
The process is initiator-driven, requiring the receiver to be ready before the sender begins scanning.
51+
* **Network Isolation:** Ensure both devices are on the exact same SSID. Guest networks often isolate clients.
52+
* **VPN:** Disable VPNs on both devices, as they route traffic away from the local network.
53+
* **Firewall:**
54+
* **Windows:** Allow `python.exe` through the firewall.
55+
* **macOS:** Grant permissions in **System Settings \> Privacy & Security \> Local Network**.
9356

94-
### Sending Files (Sender's Steps)
57+
-----
9558

96-
1. Open Seamless on both the sender and the receiver.
97-
2. The **Receiver** must click **"Receive Files"** first to start listening.
98-
3. On the **Sender**, click **"Send Files"** and select the file(s) you wish to transfer.
99-
4. Click **"Scan Network"** and wait for the receiver's name to appear.
100-
5. Select the **Receiver's name** from the list to begin the transfer.
59+
## Development Setup
10160

61+
### Tech Stack
10262

103-
---
63+
* **Desktop:** Python 3.x, CustomTkinter, Native Sockets.
64+
* **Android:** Kotlin, Coroutines (min SDK: Android 7.0).
10465

105-
## Troubleshooting
66+
### Desktop (Windows / Linux / macOS)
10667

107-
If devices fail to connect, check the following common issues:
68+
Requires Python 3.8+.
10869

109-
* **Network Consistency:** Verify both devices are connected to the **exact same Wi-Fi SSID**. Ensure neither device is connected to a "Guest" network, as these often isolate clients.
110-
* **VPN Interference:** Local network traffic is often bypassed by VPNs. Disable any active VPNs on both the sender and receiver.
111-
* **Firewall:**
112-
* **Windows:** Allow `python.exe` and the Android app through your firewall for both Private and Public networks.
113-
* **macOS:** Check **System Settings > Privacy & Security > Local Network** and ensure your terminal/IDE has permission enabled.
70+
```bash
71+
git clone https://github.com/iman-zamani/seamless.git
72+
cd seamless
73+
pip install customtkinter
74+
python seamless.py
75+
```
11476

115-
---
77+
### Android
11678

117-
## Protocol Details
79+
Open the `Android/` directory in **Android Studio**. Sync Gradle files and run on a connected device or emulator.
11880

119-
Seamless uses a simple, raw protocol built on standard socket primitives:
81+
### Protocol Overview
12082

121-
* **Discovery Protocol:** UDP broadcast on port `5000`.
122-
* Listening devices bind to `0.0.0.0:5000`.
123-
* Broadcasting device sends `HERE:Username` to the subnet broadcast address (e.g., `192.168.1.255`).
124-
* **Transfer Protocol:** Raw TCP socket on port `5001`.
125-
* **Header Format:** `filename<SEPARATOR>filesize\n`
126-
* **Body:** The raw binary data of the file is streamed immediately following the header, in 64KB chunks.
83+
* **Discovery:** UDP Broadcast on port `5000`. Payload: `HERE:Username`.
84+
* **Transfer:** TCP Stream on port `5001`.
85+
* **Header:** `filename<SEPARATOR>filesize\n`
86+
* **Body:** Binary file data.
12787

128-
---
88+
-----
12989

13090
## License
13191

132-
This project is licensed under the **GPL (General Public License)**. See the `LICENSE` file in the repository for full details.
92+
Licensed under the **GPL (General Public License)**. See `LICENSE` for details.
93+

0 commit comments

Comments
 (0)