Hi all! :)

A short HOWTO:
//////////////

Just some little steps to convert your favorite Stepmania stepfiles (.SM) to Beat2x keyfiles (.BXE):
	1. Download oggenc2.exe and oggdec.exe from http://www.rarewares.org/ogg.php
	2. Download lame.exe from http://www.rarewares.org/mp3-lame-bundle.php
	3. Create a new folder 
	4. Copy all Stepmania songsfolders you wish to convert in it
	5. Extract the sm2bxe archive into the root of your folder (at least these files are needed: sm2bxe.vbs, convert_sm2bxe.cmd, oggenc2.exe, oggdec.exe & lame.exe)
	6. Run convert_sm2bxe.cmd
	7. All results of the conversion process will then be in a newly created subfolder called: ".\_converted"

An example result can be:
	.\_converted\My favorite Song\Favorite_01BEGINNER.bxe
	.\_converted\My favorite Song\Favorite_03EASY.bxe
	.\_converted\My favorite Song\Favorite_06MEDIUM.bxe
	.\_converted\My favorite Song\Favorite_09HARD.bxe
	.\_converted\My favorite Song\Favorite_11CHALLENGE.bxe
	.\_converted\My favorite Song\Favorite.nam					(this files includes the original name included in converted SM file)
	.\_converted\My favorite Song\Favorite.ogg					
	.\_converted\My favorite Song\Favorite.log					(If something went wrong while converting the song - you might find some usefull information in there.)

Note: For a detailed step-by-step guide, please take a look at TUTORIAL.txt.
	
Some comments & hints:
//////////////////////

I read some threads on the internet with questions about sm2bxe. Some of them might be answered in this section:
	- IMPORTANT: While building your own songlist.bxs files with any version of Microsoft Windows: Use an editor which can handle LF-only text files (unix formated). My personal favorite: http://www.emeraldeditor.com/ (you can switch to Unix format inside its menu at "Document/Fileformat/Unix format (LF only)"
	- With the current release you can manipulate sm2bxe's conversion process (defining which Stepmania note should be converted to what Beat2x note). Please read the commandline parameters section below for more details.
	- Every Stepmania song folder needs to have at least 2 files in it: 1x SM-file, 1x OGG or MP3 file
	- While the conversion process, ogg and mp3 files will be reencoded to 128kbps at 44.1 KHz ogg files. The best format to use with Beat2x (e.g. Beat2x can not playback 48 KHz encoded ogg files in the right speed!). If you do not wish to reencode all ogg or mp3 files, take a look inside "convert_sm2bxe.cmd" to disable reencoding.
	- dwi stepfiles are NOT supported. To convert dwi stepfiles to bxe keyfiles, use dwi2bxe 1.3 freeware tool by furrtek (can be obtained from http://archive.gp2x.de/cgi-bin/cfiles.cgi?0,0,0,0,15,1410).
	- sm2bxe's mainpart is a vbs script. To run this script, you need to have "Windows Scripting Host 5.7" installed & you need to own the rights to run those WSH scripts. 

Commandline parameters of sm2bxe.vbs:
/////////////////////////////////////

	usage: cscript sm2bxe.vbs ".\PATH\FILE.sm" [/F1:{FILTERSEQU}] [/F2:{FILTERSEQU}] [/F3:{FILTERSEQU}] [/nodefaults] [/log:{0|1|2|3}]
	
	- IMPORTANT: The filename and path needs to be the first parameter of SM2BXE.

	- Filters are optional. They can be used to manipulate source notes and output notes. If you dont set them, the filters will be set to default settings as follows:
	
		Pre-filter block:
		-----------------
			Filter 1 - drop or convert illegal notes	
										default filter settings are: /F1:2=1,3=0,4=1,M=0
			Filter 2 - pre-convert steps (e.g. leaving jumps, reducing complexity of hands, leaving single notes)	
										default filter settings are: /F2:1100=1100,0011=0011,1010=1010,0101=0101,1001=1001,0110=0110,1101=1100,1011=0011,1110=1100,0111=0110,1111=1001,1000=1000,0100=0100,0010=0010,0001=0001
											
		Main-filter block:
		------------------
			Filter 3 - converting steps to BXE notes (e.g. jumps, normal notes)		
										default filter settings are: /F3:1100=L,0011=R,1010=L,0101=R,0110=L,1001=R,1000=A,0100=X,0010=Y,0001=B

		Explanation:
		------------
			- F1: convert hold notes(2) to normal notes(1), convert hold-end notes(3) to no-notes (0), convert begin-roll notes (4) to normal notes (1), convert mines (M) to no-notes (0)
					(unsupported notes will be dropped)
			- F2: keep jumps & convert right hand to LD, convert left hand to UR, convert left hand to LD, convert right hand to UD, convert both hand to LR & keep single notes
					(keep jumps, drop hands, keep single notes)
			- F3: convert LD to L, convert UR to R, convert LU to L, convert DU to L, convert LR to R,
	  			  convert L to A, convert D to X, convert U to Y, convert R to B
	  			  	(jumps will be converted to L/R buttons, normal notes will be set)

	  	The complete filter sequence order is always F1-F2-F3. You are absolutly free in design of your own filter rules. If you
	  	missed to set a filter or filter rule shown above, it will be set with default values. Use /nodefaults parameter
	  	to prevent sm2bxe to use default filter rules.
	  	
	  	Please refer to TUTORIAL.txt or "http://www.stepmania.com/wiki/The_.SM_file_format" for more details about the SM fileformat and sm2bxe parameters.

	- The "nodefaults" parameter will instruct sm2bxe to not to use default values, if a complete filter or some filter rules are missing.
	  Missing filter rules or values will then be set to 0000 notes.
	  
	- The "log" parameter will instruct sm2bxe to increase or decrease its logging behavior. Default is loglevel 2.
	
		Explanation:
		------------
			- 0: = info logging only
			- 1: = beat changes
			- 2: = note sets
			- 3: = note analyses & ext. note sets
			
Song sources:
/////////////

If you are a non Stepmania/ITG/DDR player, it might be good for you to have a starting point seeking out for Stepmania compatible songs (simfiles). Google should always be your first address to ask for: http://www.google.com/search?hl=com&q=stepmania+simfiles+download. If you dont find that much interessting stuff, just ask for jeffrey.
	
Comments & bugs:
////////////////

If you find some bugs or have some comments, ill be glad to hear from you. Just send me a PM at forum.gp2x.de :)

Have fun!
	-Zwirch

Version history:
- Version 1.1
	* implementation of filter sets
	* added loglevel changer
	* added mp3 support for Stepmania songs
	* "convert_sm2bxe.cmd" now accepts commandline parameters for sm2bxe.vbs
	* extended README.txt
	* new file TUTORIAL.txt
	* new toolset to create songpacks for Beat2x (see TUTORIAL.txt for more info)

- Version 1.0 (initial release)
	* prove-of-concept
	* basic conversion

	
	
### Version information:
### This README file is created for sm2bxe version Version 1.1
### Corresponding freeware archive package name is: sm2bxe_v1.1_20090122.rar