diff --git a/README.md b/README.md
new file mode 100644
index 0000000..168ffb2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,185 @@
+# Maya Media Plane Node
+
+A Maya plugin for displaying video frames in Maya Viewport 2.0.
+
+## Features
+
+- **Video Decoding**: Uses FFmpeg to decode MP4 and other video formats
+- **Frame Rate Synchronization**: Automatically adjusts playback rate based on Maya's timeline frame rate
+- **Playback Control**: Adjustable video playback rate (0.25x - 4.0x)
+- **Post-Processing Effects**:
+  - Crop
+  - Resize
+  - Flip
+- **Frame Caching**: Video frame caching mechanism for smooth playback
+
+## Requirements
+
+- Maya 2023 or higher
+- CMake 3.14+
+- Visual Studio 2019 or higher
+- FFmpeg (included)
+
+## Project Structure
+
+```
+MediaPlane/
+├── CMakeLists.txt              # Top-level CMake configuration
+├── CMakePresets.json           # CMake preset configurations
+├── cmake/
+│   └── modules/
+│       ├── FindMaya.cmake      # Maya SDK finder module
+│       └── FindFFmpeg.cmake    # FFmpeg finder module
+├── src/
+│   └── MayaImagePlaneNode/
+│       ├── CMakeLists.txt      # Plugin CMake configuration
+│       ├── Plugin.cpp          # Maya plugin entry point
+│       ├── MayaMediaPlaneNode.h    # Node header file
+│       ├── MayaMediaPlaneNode.cpp  # Node implementation
+│       ├── FFmpegVideoDecoder.h   # FFmpeg decoder header
+│       ├── FFmpegVideoDecoder.cpp # FFmpeg decoder implementation
+│       ├── FrameCache.h        # Frame cache header
+│       ├── FrameCache.cpp      # Frame cache implementation
+│       └── MediaPlane.mod      # Maya module file
+├── test/
+│   ├── test_plugin.py          # Python test script
+│   ├── test_maya_plugin.cpp    # C++ test code
+│   └── test_viewport.mel       # MEL test script
+└── docs/                       # Documentation directory
+```
+
+## Build Instructions
+
+### Using CMake GUI
+
+1. Open CMake GUI
+2. Set source code directory to `MediaPlane`
+3. Set build directory to `MediaPlane/build`
+4. Click Configure, select Maya 2023 version
+5. Click Generate
+6. Open the generated solution and build
+
+### Using Command Line
+
+```bash
+# Navigate to project directory
+cd MediaPlane
+
+# Create build directory
+mkdir build
+cd build
+
+# Configure project
+cmake .. -G "Visual Studio 17 2022" -DMAYA_VERSION=2023
+
+# Build project
+cmake --build . --config Release
+
+# Install plugin
+cmake --install . --config Release
+```
+
+## Installation
+
+1. After building, the plugin will be installed to Maya 2023's plug-ins directory
+2. You can also manually copy the generated `.mll` file to Maya's `plug-ins` directory
+
+### Manual Installation
+
+Copy the compiled `MayaMediaPlaneNode.mll` to:
+
+```
+C:\Program Files\Autodesk\Maya2023\plug-ins\
+```
+
+## Usage
+
+### Load Plugin in Maya
+
+1. Open Maya 2023
+2. Menu: Window > Settings/Preferences > Plug-in Manager
+3. Browse and select `MayaMediaPlaneNode.mll`
+4. Check Loaded
+
+### Create Media Plane Node
+
+```mel
+// MEL command
+createNode MediaPlane;
+```
+
+### Set Video File
+
+```mel
+// Set video path
+setAttr "MediaPlane1.videoFile" -type "string" "C:/path/to/video.mp4";
+```
+
+### Attribute Reference
+
+| Attribute Name | Short Name | Type | Description |
+|---------------|------------|------|-------------|
+| videoFile | vf | string | Video file path |
+| currentTime | ct | double | Current time |
+| frameRate | fr | double | Frame rate (1-240) |
+| playbackRate | pr | double | Playback rate (0.25-4.0) |
+| useMayaFrameRate | umf | boolean | Use Maya frame rate |
+| loop | lp | boolean | Loop playback |
+| postEffectCrop | pec | double4 | Crop (x, y, width, height) |
+| postEffectResize | per | double2 | Resize (width, height) |
+| postEffectFlip | pef | int2 | Flip (horizontal, vertical) |
+| cachePolicy | cp | int | Cache policy (0-2) |
+| cacheSize | cs | int | Cache size (MB, 16-2048) |
+| clearCache | cc | boolean | Clear cache |
+
+### Output Attributes
+
+| Attribute Name | Short Name | Type | Description |
+|---------------|------------|------|-------------|
+| outFrameWidth | ofw | int | Output frame width |
+| outFrameHeight | ofh | int | Output frame height |
+| outFrameTimestamp | oft | double | Output frame timestamp |
+| outFrameCount | ofc | int64 | Total frame count |
+| outIsValid | oiv | boolean | Has valid frame |
+| outCacheHitRatio | och | double | Cache hit ratio |
+| outFrameData | ofd | int | Frame data validity flag |
+
+## Testing
+
+### Test Plugin Loading with mayapy.exe
+
+```bash
+"C:\Program Files\Autodesk\Maya2023\bin\mayapy.exe" test/test_plugin.py
+```
+
+### Test Viewport Display with maya.exe
+
+1. Open Maya
+2. Load the plugin
+3. Execute MEL script: `source test/test_viewport.mel`
+
+## Technical Details
+
+### Dependencies
+
+- Maya API (Maya 2023)
+- FFmpeg (libavcodec, libavformat, libavutil, libswscale)
+
+### Thread Safety
+
+- Decoder is protected by mutex
+- Cache is protected by mutex
+
+### Cache Strategies
+
+- 0: Auto cache
+- 1: Preload all frames
+- 2: On-demand cache
+
+## License
+
+MIT License
+
+## Authors
+
+MediaPlane Team