GGWavePlayerLib 1.0.1

GGWavePlayerLib

A simple and elegant NuGet package that provides an easy way to play and save GGWave audio by encoding text messages into sound waves, built with VB.NET but fully compatible with C# and F#.

📋 Description

GGWavePlayerLib encapsulates the GGWave encoding, decoding, and audio playback logic from ggwave.net, eliminating the need for boilerplate code. With just a few lines of code, you can convert text messages into audio waves and play them through speakers, save them as WAV files, or decode audio waves back into text messages.

Note: The DecodeGGWave function outputs debug messages to the console when it works smoothly. This behavior comes from the underlying ggwave.net library and is not part of this wrapper library.

✨ Features

• Play GGWave Audio - Directly play encoded messages through system speakers
• Save to WAV Files - Export encoded audio to standard WAV format
• Decode GGWave Audio - Convert audio waves back into text messages (NEW in version 1.0.1)
• Multiple Sample Rates - Choose from 4 different quality levels
• Protocol Support - Support for various GGWave protocols (audible, ultrasound, dualtone, monotone, and custom)
• Encoding Options - Support for both ASCII and UTF-8 text encoding
• Simple API - Clean, intuitive interface with minimal code required

🔧 Requirements

• .NET 8.0 or higher (works with C#, F# and VB.NET)
• Dependencies:
  • ggwave.net v0.2.1
  • NAudio v2.2.1

📦 Installation

Install the package via command line:

dotnet add package GGWavePlayerLib

Or using .NET CLI / Package Manager Console:

Install-Package GGWavePlayerLib

🚀 Quick Start

Playing GGWave Audio

Imports GGWavePlayerLib

' Play a simple message with default settings
GGWavePlayer.PlayGGWave("Hello world!", GGWaveRate.CDQuality)

' Play with custom protocol and UTF-8 encoding
GGWavePlayer.PlayGGWave("吃了吗，世界？",
    GGWaveRate.Professional, ProtocolId.AudibleNormal, useUtf8:=True)

Saving GGWave to WAV File

Imports GGWavePlayerLib

' Save a message to a WAV file
GGWavePlayer.SaveGGWave("Secret message", GGWaveRate.CDQuality, "output.wav")

' Save with custom settings
GGWavePlayer.SaveGGWave(
    "Important data", GGWaveRate.Professional, "important.wav",
    ProtocolId.AudibleFastest, useUtf8:=False
)

Decoding GGWave Audio

Imports GGWavePlayerLib

' Decode audio bytes back to text
Dim audioBytes As Byte() = GGWavePlayer.PlayGGWave("Hello world!", GGWaveRate.CDQuality)
Dim decodedMessage As String = GGWavePlayer.DecodeGGWave(audioBytes, GGWaveRate.CDQuality)
Console.WriteLine($"Decoded message: {decodedMessage}")

' Decode from a WAV file (requires reading the file first)
Dim wavBytes As Byte() = File.ReadAllBytes("output.wav")
Dim decodedFromFile As String = GGWavePlayer.DecodeGGWave(wavBytes, GGWaveRate.CDQuality)
Console.WriteLine($"Decoded from file: {decodedFromFile}")

📚 API Reference

GGWaveRate Enum

Represents the audio sample rate for GGWave encoding. Higher rates provide better audio quality but require more bandwidth.

ProtocolId Enum

Represents the protocol ID for GGWave encoding. These values are wrapped from the original ggwave.net.Native.ProtocolId enum.

Audible Protocols:

• AudibleNormal - Standard audible transmission (default)
• AudibleFast - Faster audible transmission
• AudibleFastest - Fastest audible transmission

Ultrasound Protocols:

• UltrasoundNormal - Standard ultrasound transmission
• UltrasoundFast - Faster ultrasound transmission
• UltrasoundFastest - Fastest ultrasound transmission

Dualtone Protocols:

• DualtoneNormal - Standard dual-tone transmission
• DualtoneFast - Faster dual-tone transmission
• DualtoneFastest - Fastest dual-tone transmission

Monotone Protocols:

• MonotoneNormal - Standard monotone transmission
• MonotoneFast - Faster monotone transmission
• MonotoneFastest - Fastest monotone transmission

Custom Protocols:

• Custom0 through Custom9 - Custom protocol configurations

PlayGGWave Method

Plays the GGWave audio for the given message through the system speakers, with the audio bytes returned to the caller.

Public Function PlayGGWave(
    message As String, waveRate As GGWaveRate,
    Optional protocolId As ProtocolId = ProtocolId.AudibleNormal,
    Optional useUtf8 As Boolean = False
) As Byte()

Parameters:

• message - The text message to encode and play
• waveRate - The sample rate for audio encoding (see GGWaveRate enum)
• protocolId - The GGWave protocol to use (default: AudibleNormal)
• useUtf8 - Whether to use UTF-8 encoding instead of ASCII (default: False)

Returns:

• Byte() - The audio bytes that were played

SaveGGWave Method

Saves the GGWave audio for the given message to a WAV file, with the audio bytes returned to the caller.

Public Function SaveGGWave(
    message As String, waveRate As GGWaveRate, filePath As String,
    Optional protocolId As ProtocolId = ProtocolId.AudibleNormal,
    Optional useUtf8 As Boolean = False
) As Byte()

Parameters:

• message - The text message to encode and save
• waveRate - The sample rate for audio encoding (see GGWaveRate enum)
• filePath - The path where the WAV file will be saved
• protocolId - The GGWave protocol to use (default: AudibleNormal)
• useUtf8 - Whether to use UTF-8 encoding instead of ASCII (default: False)

Returns:

• Byte() - The audio bytes that were saved to the file

DecodeGGWave Method

Decodes GGWave audio bytes back into a text message.

Public Function DecodeGGWave(
    audioBytes As Byte(), waveRate As GGWaveRate,
    Optional protocolId As ProtocolId = ProtocolId.AudibleNormal
) As String

Parameters:

• audioBytes - The audio bytes to decode (from PlayGGWave, SaveGGWave, or a WAV file)
• waveRate - The sample rate used for the original audio encoding (see GGWaveRate enum)
• protocolId - The GGWave protocol used for the original encoding (default: AudibleNormal)

Returns:

• String - The decoded text message

💡 Usage Tips

1. Choose the Right Sample Rate:

   • Use StandardLow or StandardHigh for basic applications where file size matters
   • Use CDQuality for most general-purpose applications
   • Use Professional for high-fidelity applications

2. Protocol Selection:

   • AudibleNormal is the default and works well for most cases
   • Use Fast or Fastest variants for quicker transmission
   • Use Ultrasound protocols for applications requiring inaudible transmission
   • Use Dualtone or Monotone for specific hardware compatibility

3. Encoding:

   • Use ASCII (useUtf8:=False) for English text and basic characters
   • Use UTF-8 (useUtf8:=True) for international characters and emojis

4. Decoding Best Practices:

   • When decoding, use the same sample rate and protocol that was used for encoding
   • For WAV file decoding, ensure the file contains valid GGWave audio data
   • The PlayGGWave and SaveGGWave methods now return audio bytes for easy decoding
   • Decoding works with both ASCII and UTF-8 encoded messages automatically

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

If you encounter any issues or have questions, please open an issue on the project repository.

🙏 Acknowledgments

• Built on top of the excellent ggwave.net library
• Audio playback powered by NAudio
• Based on the GGWave project by Georgi Gerganov